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Preface 


Manual Objectives 


This manual describes how to use the VAX-11 PL/I compiler on the 
VAX/VMS operating system and contains detailed explanations of the exten- 
sions made to the standard PL/I language for VAX-11 PL/I. It includes infor- 
mation on the VAX/VMS commands and utilities to aid in program develop- 
ment, as well as information to assist in writing PL/I programs that take 
advantage of features of the file system and the operating system. 


Audience Assumptions 


This manual is designed for programmers who have a working knowledge of 
PL/I and some familiarity with the VAX/VMS operating system and its com- 
mand language, DCL. 


Structure of This Document 


This manual has four parts: 


Part I, ““The Command Language,” provides information on the commands 
and utilities available for program development. This part provides infor- 
mation on compiling, linking, and executing VAX-11 PL/I programs on 
VAX/VMS. 


Part II, “The File System,” provides specific information on the VAX-11 
file system, RMS (Record Management Services). This part describes the 
relationship between PL/I input/output statements and VAX/VMS files, | 
and provides detailed information on the ENVIRONMENT options of 
VAX-11 PLA, I/O statement options, and file-handling built-in sub-_ 
routines. This part provides examples of I/O to sequential, relative, and 
indexed sequential files and of file sharing. 


Part ITI, “Procedure Calling and Condition Handling,” provides detailed 
information on calling procedures written in other languages from PL/I 
programs, including using system global symbols and return status values, 
and on condition handling. 


XV 


Introduction to 
VAX-11 PL/I 
AA-H950A-TE 


© Provides an overview of the 
PL/I G Subset language 
e Summarizes the VAX-11 extensions 


to the PL/I language 
e Introduces the tools for PL/I 
program development on VAX/VMS 


a, 





VAX-11 PL/I VAX-11 PL/I 
Encyclopedic Reference User's Guide 
AA-H952A-TE AA-H951A-TE 


* Contains a complete definition 
of the VAX-11 PL/I language 

* Lists the semantics and syntax 
rules for all standard PL/I 
language elements 


Describes how to use 

VAX/VMS to compile, link, and run 
PL/I programs 

Provides detailed information 

on input/output processing 


Explains extensions to VAX-11 
PL/I to Support procedure calling 
and condition handling 





VAX-11 PL/I 
‘Language Summary 
AV-J757A-TE 


© Gives a concise summary of PL/! 
attributes, statements, built-in functions, 
and conversion rules 

Provides quick reference for VAX-11 PL/I 
ENVIRONMENT options. the ASCII character set. 
and PLI command qualifiers and options 





VAX-11 PL/I installation and 
System Management Guide 
AA-J179A-TE 


* Gives step-by-step instructions for 
installing the VAX. 11 PL/I compiler 


* Describes how to diagnose and report 
problems with the coropiler 





VAX/VMS Documentation 


¢ Contains a complete definition 
of the VAX/VMS operating system 
and its command language, DCL 


¢ Provides specific reference 
information for all operating 
system components, facilities, 
and utilities 





The titles listed below may be of interest 
to VAX-11 PL/I programmers: 


VAX/VMS Command Language User’s Guide 
VAX-11 Linker Reference Manual 
VAX-11 Record Management Services Reference Manual 


Introduction to VAX-11 Record Management Services 
VAX-11 SORT User's Guide 


VAX-11 DECnet User's Guide 


VAX/VMS System Services Reference Manual 


VAX-11 Run-Time Library Reference Manual 
VAX-11 Utilities Reference Manual 


Figure 1: Documentation for VAX-11 PL/I Programmers 


Xvi 


Part I 
The Command Language | 


Chapter 1 
Introduction to Program Development on VAX/VMS 


The VAX-11 operating system, VAX/VMS, and its command language, DCL, 
provide numerous tools and utilities for program development. This chapter 
summarizes the basic things you need to know to use the command language 
in developing and testing your PL/I programs, including: 


e The commands you use to create, compile, link, and execute PL/I programs 
e The rules for specifying input and output files for commands and programs 


e The commands available to you for file creation, modification, and mainte- 
nance 


For a tutorial introduction to these concepts, see the VAX/VMS Primer. For 
detailed definitions of commands and file specifications, see the VAX/VMS 
Command Language User’s Guide. 


1.1. VAX/VMS Commands for Program Development 


Figure 1-1 illustrates the DCL commands you use to create and run PL/I 
programs. 


The commands are shown in their simplest forms. You can, however, specify 
qualifiers on these commands to request special processing or to indicate a 
special type of input file, as in these examples: 

$ PLI/LIST=LP: METRIC 


¢ LINK METRIC;sMYLIB/LIBRARY 


In this PLI command, the /LIST qualifier requests the compiler to create a 
listing file for the source program METRIC.PLI and to output it on a line 
printer device (LP: is the device name for line printers). 


~The LINK command uses the /LIBRARY qualifier to indicate that the input 
file MYLIB is a program library consisting of object modules. The linker will 
automatically search this library to locate external procedures and external 
variables that are referenced in the source file METRIC.PLI. 
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1.1.1. Hints for Entering Commands 


The next few chapters of this manual describe in detail the commands of 
specific interest to PL/I programmers. You should note the following hints on 
entering commands: 


e You can truncate (shorten) any command name or qualifier name to four 
characters. In some cases, fewer than four characters are accepted, as long 
as there is no ambiguity about the name of the command. 


e You must precede each qualifier name with a single slash character (/). 


e If you omit a required parameter, for example, a file specification, the DCL 
command interpreter will prompt you to enter it. 


e You can enter a command on as many lines as you wish, as long as you end 
each continued line with a hyphen (-) character. 


e After you have entered a complete command, you must press to pass the 
command to the system for processing. 


e You can cancel a command before the final by using CTRLY). 


You can interrupt command execution by using C1RLY). To resume the inter- 
rupted command, enter the CONTINUE command. To stop processing 
completely after pressing CIRLY), you can begin entering other DCL 
commands. 


If you make an error entering a command, for example if you misspell a 
command or qualifier name, the command interpreter issues an error message 
and you must reenter the entire command string. 


1.1.2 HELP 


You can obtain online information about a command, its parameters, or qual- 
ifiers by entering the HELP command. This command responds to.a request 
for help on a command name by displaying a brief description of the 
command and by listing the additional information you can obtain. For exam- 
ple, if you enter the following: 


€ HELP PRINT. 


The HELP command response displays a description of the PRINT command 
and a list of its qualifiers. To get further information, you must reenter the 
HELP PRINT command with an additional parameter: the name of the 
qualifier you want information about. For example: 


$ HELP PRINT /JOB_COUNT 


The HELP command responds to this request with a description of the syntax 
for entering the /JOB_COUNT qualifier. 


The HELP command also provides detailed information about the PLI 
command and the VAX-11 PL/I language. You can obtain information about 
PL/I topics by specifying a PL/I keyword. For example: 


$ HELP PLI INDEX 


The HELP command responds to this request by displaying the syntax of the 
INDEX built-in function. 
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Table 1-1: Summary of File Specification Syntax 


node 1 - 6 characters local node node: ‘node: : defines a path 
terminated by :: node"access-control": : in 
VAX/VMS, username password 
node: :"non-VMS-file-specification" 























valid mnemonic or | SYS$DISK 
logical name 
A-Z 

0 - 65535 


-card reader NET -network device 
DB -disk device MB -mailbox 

DM -RK06/7 disk MT -magnetic tape 
DX -floppy disk TT -terminal 
-line printer TU -cartridge tape 






































[*] all directories 
[name...] all directories in path 

[*...] all subdirectories in all directories 
[-.name] back up a directory 


1 - 9 characters current default 
up to 8 names, 
separated by 


periods (.) 


directory 
[name] 
[name.name...] 


















* 





— all file names 
*string* — match all names containing “‘string’ 
strScng — match any character in Cc position 


filename 0 - 9 characters Input: temporary 
defaults apply 
Output: same as 


input file 
Applied by 
command; temporary 
defaults apply 










> 















0 — 3 characters Wild card rules same as for filename 


preceded by . 


filetype 

















Command Input Output 





PLI PLI, TLB OBJ, LIS 
LINK OBJ, OLB EXE, MAP 
LIBRARY OBJ OLB 
LIBRARY/TEXT TXT TLB 

RUN EXE 

PRINT, TYPE LIS 




















0 - 32767 
preceded by ; or. 


* — all versions 
; — use most recent version 


version Input: highest 


Output: highest + 1 


1.2.1 Temporary Defaults 


Many VAX/VMS file-handling commands use temporary defaults under 
certain conditions. When a command such as PRINT or TYPE accepts a list 
of input file specifications, it uses explicit elements of one file specification as 
a temporary default for subsequent file specifications. Some examples follow: 
¢ PRINT CPROJECT.DATAIALPHA+BETA. DAT +GAMMA 


The PRINT command uses the default input file type LIS for the first input 
file and the file type DAT as specified for the second input file. It then applies 
the temporary default DAT to the file GAMMA. The PRINT command prints 
the highest existing versions of ALPHA.LIS, BETA.DAT, and GAMMA.DAT 
from the directory [PROJECT.DATA] on the current default device. 


¢ PRINT CPROJECT.BDATAIFOREST.THT>+.DAT+.REF 


Here, the PRINT command uses the temporary default FOREST as a file 
name and prints the files FOREST.TXT, FOREST.DAT, and FOREST.REF. 


Introduction to Program Development 1-5 


You must specify /GROUP on a DEFINE command to place a name in the 
group logical name table, and you must have the GRPNAM user privilege. 


e System logical name table. There is a single system logical name table. The 
logical names in this table can be accessed by all users. You must specify 
/SYSTEM on a DEFINE command to place a name in the system logical — 

~ name table, and you must have the SYSNAM user privilege. 


1.2.3.1 Logical Name Translation — When the system attempts to locate an 
equivalence name for the name of a PL/I file, or for a portion of a file specifi- 
cation, it is said to be performing logical name translation. When the system 
translates a logical name, it searches the process, then group, then system 
logical name tables, in that order, for a logical name. Each time the system 
translates a logical name, it examines the result to see if it still contains a 
logical name. If it does, it translates the result. This recursive translation 
occurs until the file specification is complete or until ten recursive transla- 
tions have been made. 


You can determine the current equivalence for a logical name by entering the 
SHOW TRANSLATION command. For example: 


$ SHOW TRANSLATION SRC 

SRC = [CPROJECT.SRCI {Process} 
The response gives the translation and indicates that the logical name SRC 
was found in the process logical name table. 


A logical name assignment is deleted either when a new definition is given for 
the name or when the name is explicitly deleted with a DEASSIGN 
command. For example: 


$ DEASSIGN SRC 


This command deletes the logical name table entry for the logical name SRC. 


1.2.3.2 Uses for Logical Names — VAX/VMS system programs use logical 
names in many ways. For example, the PL/I compiler and the linker use 
logical names to provide default libraries for INCLUDE modules and object 
module libraries, respectively. These uses of specific logical names are de- 
scribed in Sections 2.4.6, “Default PL/I Libraries,” and 3.3.3, “Default User 
Object Module Libraries.” 


A principal use for programmers is to provide device and file independence for 
executable program images or command procedures. For example, the name 
you give a file constant in a PL/I source program can be a logical name: each 
time you execute the program, you can issue a DEFINE command to provide 
a different equivalence name for the PL/I file. The relationship between PL/I 
file constants and VAX/VMS file specifications is described in detail in Chap- 
ter 5, “Overview of the File System.” 


The use of logical names is not limited to file-related functions, however. For 
an example of using logical names to pass string arguments to PL/I main 
procedures, see Section 4.4.3, “Passing Data Via Logical Names.” 
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Table 1-3: VAX/VMS Commands for File Maintenance 


Category Command Function 


File creation 


Correcting and 
modifying files 


Cataloging and 
organizing files 


Copying and 
backing up files 


Deleting files 


CREATE 


EDIT 
EDIT 
CREATE/DIRECTORY 


DIRECTORY 


LIBRARY 
RENAME 


SET DEFAULT 


ALLOCATE 
INITIALIZE 
MOUNT 


COPY 
DELETE 


PURGE 


Creates a file from records or data that follows in the input 
stream; for example, lines entered from a terminal or placed 
in a batch input file. 


Invokes one of the VAX/VMS interactive editing programs, 
for example, SOS, EDT, or EDI. 


Invokes one of the interactive editors to make changes or 
additions to a disk file. 


Establishes a new directory or a hierarchy of directories to 
catalog files. 


Lists files and information about them. Can list files with 
common file names or file types, files in one or more directo- 
ries, files created since a certain date, and so on. 


Creates and maintains libraries of INCLUDE text modules 
and libraries of object modules. 


Changes the directory in which a file is cataloged; or changes 
the file name, file type, or version number of a file or file. 


Changes the current default device or directory. 


Provide device-handling and control commands that let you 
access data written on nonsystem disks, on magnetic tapes, 
or on punched cards; or to output data to a disk or tape. 


Copies the contents of a file or files to another file or files. 


Makes the contents of a file inaccessible by removing its 
directory entry. 


Deletes a specified number of earlier versions of a file or a 
group of files. 
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Chapter 2 
Compiling PL/I Programs 


This chapter describes how to use the PLI command to compile your source 
programs into object modules. It discusses: 


e The functions of the compiler 
e PLI command syntax and qualifiers 
¢ Compiler diagnostic messages and error conditions 


e INCLUDE files and libraries 


2.1 Functions of the Compiler 


The primary functions of the compiler are to verify the PL/I source statements 
and to issue messages if there are any errors; to generate machine language 
instructions from the source statements of the PL/I program; to group these 
instructions into units called program sections, and to write the program 
sections into an object module. 


When it creates an object module, PL/I provides the linker with the following 
information: 


e The module name. It takes this name from the name of the main procedure 
in the source program, that is, the procedure that specifies OPTIONS 
(MAIN). Note that this is not necessarily the name of the file containing the 
object module. If no procedure specifies OPTIONS(MAIN), the name of the 
object module is the name on the first procedure statement in the source 
file. 


A list of all entry points, external variables, and global symbols that are 
declared in the module. The linker uses this information when it binds two 
or more modules together and must resolve references to the same names in 
the modules. 


e A summary of the program sections it has created and their attributes, the 
generated machine instruction text, and relocation information. 


2-1 


You must separate multiple input file specifications with either commas (,) 
or plus signs (+). The commas and plus signs have different meanings, as 
follows: 


¢ Commas delimit PL/I source files to be compiled separately. PL/I com- 
piles each file and creates an object module for each. 


e Plus signs delimit files to be concatenated or libraries containing IN- 
CLUDE files. PL/I compiles the source files as a single file and creates 
one object module. Library file specifications must be qualified with the 
/LIBRARY qualifier. 


If a file specification does not contain a file type, PL/I assumes a default file 
type of PLI for a source file. If a file specification is qualified with /LIBRARY, 
PL/I assumes a default file type of TLB. INCLUDE files and INCLUDE file 
libraries are described in Section 2.4, “INCLUDE Files.” 


A single file may contain more than one PL/I procedure; PL/I concatenates 
these procedures into a single object module as decribed in Section 2.2.3, 
‘“Concatenated Input Files.” 


Command Qualifiers 


Command qualifiers request processing options of the compiler. You can 
specify qualifiers to the PLI command following the command name or 
following an individual file specification. When a qualifier is specified 
following the PLI command name, its action applies to each file in the list, 
unless overridden by a qualifier specified for an individual file. 


When a qualifier is specified following a file specification in a list of files 
separated by commas, its action is applied only to the compilation of that 
file. 

/CHECK 

/NOCHECK 
Controls the checking of array subscripts and of positional references in 
arguments to the SUBSTR built-in function. If you specify /CHECK, the 
compiler provides the following checks: 


e It checks that each reference to the SUBSTR built-in function or pseudo- 
variable lies within the string’s current length. 


e It checks that each reference to an array specifies subscripts that are 
within the bounds declared for the array. 


e It checks that all string lengths are nonnegative and that all array extents 
are positive. 


The default is /NOCHECK. /CHECK is primarily of use during initial pro- 
gram debugging; it results in the generation of additional code and, conse- 
quently, a slower program. 
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Table 2-1: PL/I Compiler Options 


Print/do not print the contents of INCLUDE files and 
modules in the program listing. 








(NOJLIST_INCLUDE 







Print/do not print the storage map of the compiled pro- 
gram in the program listing. The storage map includes a 
list of all external entry points, the size and attributes of 
all variables that are referenced in the program, and a 
program section summary and procedure definition map. 





(NO]LIST__MAP 









[NOJLIST__SOURCE Print/do not print the source program statements in the 


program listing. 







Print/do not print performance statistics in the program 
listing. 


[NOJLIST_STATISTICS 






/G_FLOAT 

/NOG_FLOAT 
For VAX-11 computers that are equipped with the appropriate hardware 
option, specifies the default representation of floating-point variables with 
a precision in the range of 25 through 53. 


By default, the compiler uses D (double-precision) floating point. Specify 
/G_FLOAT to override this default and to request the compiler to use the 
G floating-point type for these variables. 


The default and maximum precisions for all floating-point formats are 
summarized in the VAX-11 PL/I Encyclopedic Reference. 


/LIST[=file-spec] 
/NOLIST 
Controls whether a listing file is produced. 


If the PLI command is executed from interactive mode, /NOLIST is the 
default, unless the /CROSS_REFERENCE or /MACHINE_CODE quali- 
fiers are specified. If the PLI command is executed from batch mode, /LIST 
is the default. 


When /LIST is in effect, the compiler gives a listing file the same file name 
as the source file and a file type of LIS. 


If you specify a file specification with /LIST, the compiler uses that file 
specification to override the default values applied. 


You can control the contents of the listing file by specifying the /CROSS_ 
REFERENCE and /MACHINE_CODE qualifiers, and by specifying 
options on the /ENABLE qualifier. 


/MACHINE_CODE 

/NOMACHINE_CODE 
Controls whether the listing file produced by the compiler includes a listing 
of the machine language code generated during the compilation. 


For an example of a machine code listing, see Appendix A. 
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/WARNINGS 
/NOWARNINGS 
Controls whether the compiler prints messages for diagnostic warnings. 


By default, the compiler prints all diagnostic messages during compilation. 
If you specify /NOWARNINGS to override this default, the compiler does 
not print warning messages. It does, however, continue to display messages 
for informational, error, and fatal diagnostics. 


File Qualifier 


/LIBRARY 
Indicates that the associated input file is a library containing text modules 
that may be included in the compilation of one or more of the specified 
input files. 


The specification of a library file must be preceded by a plus sign. 


If the file specification does not contain a file type, PL/I assumes the 
default file type of TLB. 


For more information on creating and using INCLUDE file libraries, see 
Section 2.4, “INCLUDE Files.” 


2.2.1 PLI Command Examples 


$ PLI METRIC 


The PLI command compiles METRIC.PLI and creates the file 
METRIC.OBJ. 

$ PLI/EN@BLE#LISTOINCLUDE/MACHINE.CODE APPLIC 

$ PRINT APPLIC 

The PLI command compiles the file APPLIC.PLI and creates the files 
APPLIC.OBJ and APPLIC.LIS. The listing shows the contents of all files and 
text modules included in the compilation by %INCLUDKE statements, as well 
as a machine code listing of the program. The /LIST qualifier is not necessary 
because /MACHINE__CODE implies /LIST. The PRINT command queues a 
copy of the listing file for printing. Note that the default file type created by 
the compiler is LIS and that this is also the default file type assumed by the 
PRINT command. 


$ PLI SWITCH, TXT/CHECK 
The PLI command compiles the statements in the file SWITCH.TXT. The 


/CHECK qualifier causes the compiler to verify all array references and sub- 
string extents. 


2.2.2 Specifying Input and Output Files 


When you specify more than one input file on the PLI command, you can 
separate the names of the files with either commas or plus signs. If you 
separate them with commas, PL/I compiles each source file separately and 
creates individual listing files and object files for each. 
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In the third and fourth examples, the listing files are not saved on disk; they 
are deleted after output. 


2.2.3 Concatenated Input Files 


If you separate the names of input files with plus signs, PL/I concatenates the 
contents of the files and compiles them as if they were a single input file. It 
creates a single object file and (if /LIST is specified) one listing file for conca- 
tentated input files. 


The rules in effect for compiling concatenated input files are the same as for a 
single file that contains more than one procedure. These are as follows: 


e Only one procedure among all files that are to be concatenated may specify 
OPTIONS (MAIN); this procedure is the main entry point. 


e PL/I gives the object module the same name as the first procedure in the 
file. It gives the object module output file the same file name as the first 
input file in the command line. 


e If files contain separate level-one procedures, the procedures may call one 
another without declaration, but they may not reference internal variables 
declared within other blocks. (A level-one procedure is a procedure whose 
text is not contained within another procedure. ) 


For example, assume that the files A.PLI, B.PLI, and C.PLI have the follow- 
ing contents: 


A.PLI contains: 


A: PROCEDURE; 
DECLARE X FIXED BINARY; 
CALL B; 

END; © 


B.PLI contains: 
B: PROCEDURE OPTIONS (MAIN); 


END: 
C.PLI contains: 
C: PROCEDURE; 


END; 
These files may be concatenated in a compilation as follows: 
$ PLI A+B+C 
This command causes PL/I to create the file A.OBJ that contains an object 
module named B,; B is the main entry point. Within this module, procedures 
A, B, and C may invoke one another without declaration, but none of the 


procedures may refer to internal variables declared within the other. For 
* example, B cannot reference the variable X declared within A. 
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Source file line number n 
Specifies the source file line number of the statement that caused the error. 
Note that this line number is assigned to a statement by the compiler. It is 
not necessarily the same as the line number, if any, assigned by a text 
editing program. 


The messages produced by the VAX-11 PL/I compiler are listed in 
Appendix B. 


2.3.1 Suppressing Warning Messages and Parts of Messages 


When you compile a PL/I program, you can use the /NOWARNINGS qualifier 
to request the compiler not to display warning (severity W) messages on the 
terminal. For example: 


$ PLI METRIC/NOWARNINGS 


When PL/I compiles the file METRIC.PLI, it does not display warning 
messages on the output device. You may find this qualifier useful when you 
are compiling programs that you know contain statements that cause warn- 
ings. 


The DCL command SET MESSAGE lets you define whether you want to see 
messages displayed in their entirety or in shortened form. For example, if you 
do not want to see the %PLIG-s-ident part of messages, you can enter the 
command: 


# SET MESSAGE /NOFACILITY/NOSEVERITY “NOIDENT 


This command cancels the facility, severity, and identification portion of all 
messages and remains in effect for all commands you subsequently enter, 
until you reissue the SET MESSAGE command or log off the system. 


2.3.2 Interrupting the Compiler 


During the compilation of a file, PL/I sometimes detects an error from which 
it cannot recover, that is, an error that causes additional errors to be detected. 
For example, a syntax error in a DECLARE statement causes subsequent 
references to the variables that were declared in that statement to generate 
errors. 


When errors of this sort occur, you can halt the compilation, correct the errors, 
and restart the compiler. To do this, you can use the €7ALic) or CIRLY) key 
combinations, according to the following guidelines: 


e If you specified /LIST, and would like to examine the listing, you can press 
¢tRLic). The compiler will close the listing file it is creating. Although the file 
will not be complete (and may sometimes be empty), it often contains 
enough of the program listing, with diagnostic messages, that you can print 
it to determine which errors occurred and correct them. 
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2.4.1 Specifying INCLUDE Files 


An INCLUDE file is requested by a %INCLUDE statement in a PL/I source 
file. When the compiler reads the %INCLUDE statement during compilation 
of a source program, it begins reading from the file specified by %INCLUDE. 
When it reaches the end of the included file, it resumes reading from the 
previous input file. 


An INCLUDE file can contain a %INCLUDE statement. The maximum 
depth to which INCLUDE files can be nested is four. 


The syntax for specifying %INCLUDE is: 
%INCLUDE { ‘file- -spec * , . 
text-module-name f ’ 
file-spec 
Is a file specification enclosed in apostrophes. The file specification can be 
any valid VAX/VMS file specification, including a logical name. 


When the file specification does not completely specify the name of the 
INCLUDE file, PL/I uses the VAX/VMS system defaults for file specifica- 
tions and uses the default file type of PLI. 


text-module-name 
Specifies the 1- to 3l-character name of a text module in a library of 
INCLUDKH files or other text modules. A module name can consist of the 
alphanumeric characters or the $ or _ characters. The name of the library 
containing the module must be specified on the PLI command. 

For example, the following specifications are different: 

ZINCLUDE STATE: | 

ZINCLUDE ‘STATE ’$ 


In the first example, PL/I searches any library files specified on the PLI 
command for a module named STATE. In the second example, PL/I assumes 
that STATE is a file specification and looks for the file STATE. PLI in the 
current default directory. 


If PL/I cannot locate a specified file or module, it issues a fatal error message 
and terminates the compilation. 


2.4.2 Text Libraries 


A text library is a file that contains individual files and a table indexing them. 
The LIBRARY command creates and modifies text libraries; these libraries 
have a default file pe of TLB. To use libraries for PL/I INCLUDE files, you 
must: 


‘1. Create one or more libraries consisting of INCLUDE files. 


2. Specify the name of the INCLUDE module in a %INCLUDE statement in 
the PL/I source program. 


3. Specify the name of the library on the PLI command to compile the source 
program or define a default library. 
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This command inserts the contents of the file DECLARE.PLI into the library 
PLIFILES under the name EXTERNAL__DECLARATIONS. This module 
can be included in a PL/I source file during compilation with the statement: 


ZINCLUDE EXTERNAL..DECLARATIONS $ 
Table 2-4 summarizes the commands that create libraries and provide main- 
tenance functions. For a complete list of the LIBRARY command qualifiers, 


and for a description of other DCL commands listed in Table 2-4, see the 
VAX/VMS Command Language User’s Guide. 


Table 2-4: Commands to Control Library Files 


$ LIBRARY/TEXT/CREATE library-name file-spec,... 
$ LIBRARY/TEXT/INSERT library-name file-spec,... 





Create a library. . 











Add one or more modules to 
a library. 






Replace one or more modules $ LIBRARY/TEXT/REPLACE” lubrary-name file-spec,... 


in a library 

















Specify the names of modules 
to be added to a library. 


$ LIBRARY/TEXT/INSERT library-name file-spec/MODULE=module-name 






Delete one or more modules $ LIBRARY/TEXT/DELETE=( module-name,...) library-name 


from a library. 












Copy a module from a library 
into another file. 


$ LIBRARY/TEXT/EXTRACT=module-name library-name 












List the modules in a library. $ LIBRARY/TEXT/LIST/OUTPUT=file-spec library-name 


Rename a library or move a 
library to another directory. 


$ RENAME old-library-name new-library-name 











Delete a library. $ DELETE lbrary-name 


Copy or backup a library. $ COPY input-library-name output-library-name 


1. The LIBRARY command qualifier /TEXT indicates a text module library. By default, the LIBRARY com- 
mand assumes an object module library. 


2. REPLACE is the default function of the LIBRARY command, if no other action qualifiers are specified. If no 
module exists with the given name, /REPLACE is effectively INSERT. 


2.4.4 Specifying Library Files on the PLI Command 


When you specify a library file on a PLI command, you must precede the file 
specification of the library with a plus sign and use the /LIBRARY qualifier. 
For example: 


# PLI APPLIC+DATAB/LIBRARY 
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You can define the logical name PLI$LIBRARY in the process, group, or 
system logical name table. If the name is defined in more than one table, the 
PL/I compiler uses the equivalence for the first match it finds in the normal 
order of search (that is, the process, then group, then system table). Thus, if 
PLI$LIBRARY is defined in both the process and group logical name tables, 
the process logical name table assignment overrides the group logical name 
table assignment. 


2.4.7 Default System INCLUDE Library 


When it cannot find INCLUDE modules in libraries specified on the PLI 
command or in the default library defined by PLISLIBRARY, PL/I searches 
the library identified by the following name: 


SYS$LIBRARY:PLISYSDEF.TLB 


Where SYS$LIBRARY is normally defined by the system manager to identify 
the device and directory containing system libraries. PLISYSDEF.TLB is a 
library of INCLUDE modules supplied by VAX-11 PL/I. It contains declara- 
tions for the entry points for VAX/VMS system services, local symbol defini- 
tions required for use with system services, and variables to test return status 
values from system services. The contents of this library are described in 
detail in Chapter 19, ‘““System Services.” 


Note that you can define a second default private library by redefining the 
logical name SYS$LIBRARY. For example, if you make a copy or subset of 
PLISYSDEF.TLB or create your own library named PLISYSDEF.TLB, you 
can make this library the second search library as follows: 


# DEFINE PLISlLIBRARY OBL:CMALCOLM.LIBRARYISTATEDATA. TLE 
# DEFINESUSER SYSSLIBRARY DBI: ChALCOLM.LIBRARY I 
# PLI MAILBOX 


In this example, the DEFINE command creates process logical name table 
assignments for PLISLIBRARY and SYS$LIBRARY. When PL/I compiles 
the program MAILBOX, it searches STATEDATA.TLB and_ then 
PLISYSDEF.TLB in DB1:[(MALCOLM.LIBRARY] for any INCLUDE mod- 
ules that are specified in MAILBOX. The /USER qualifier on the second 
DEFINE command ensures that the logical name SYS$LIBRARY will be 
deassigned following the execution of the PLI command. This is neces- 
sary because other system programs (the linker, for example) that use 
SYS$LIBRARY may not execute correctly if the library is not reassigned. For 
additional information on logical names, see Section 1.2.3, ‘“‘Logical Names.”’ 
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Chapter 3 
Linking Programs 


This chapter describes how to use the linker and object module libraries to 
combine object modules into executable programs. It discusses: 


e The functions performed by the linker 
e The LINK command and its input and output files 
e Creating and using object module libraries 


The topics in this chapter are confined to areas of particular interest to PL/I 
programmers. For additional information on linker capabilities and detailed 
descriptions of LINK command qualifiers and options, see the VAX-II 
Linker Reference Manual. 


3.1 Functions of the Linker 


The primary functions of the linker are to allocate virtual memory within the 
executable image, to resolve symbolic references among modules being linked, 
to assign values to relocatable global symbols, and to perform relocation. 


For any PL/I procedure, the object module generated by the compiler contains 
calls and references to VAX-11 PL/I run-time procedures. For example, any 
procedure that contains a PUT statement requires calls to routines to convert 
noncharacter data to a character string and calls to I/O routines. 


These run-time procedures are automatically located in the default system 
object module libraries. These libraries are described in more detail in Section 
3.3.4, “System Libraries.” 


A global symbol can be any of the following: 


e The name of an external procedure or entry point. In PL/I terms, this is the 
name specified on an ENTRY statement or on a PROCEDURE statement 
in a level-one procedure, that is, a procedure at the outermost level whose 
text is not contained within the text of any other procedure. 


e The name of a variable declared with the EXTERNAL STATIC attributes. 


e The name of a variable declared with the GLOBALDEF or GLOBALREF 
attribute. Variables of this type are described in Chapter 15, “Global 
Symbols.”’ 


Table 3-1: LINK Command Qualifiers 


Request output files /EXECUTABLE|=file-spec] /EXECUTABLE=name.EXE, where name 
and define a file /SHAREABLE/=ftle-spec] is the name of the first input file. 
specification. /SYMBOL__TABLE|-=file-spec] /NOSHAREABLE 

/NOSYMBOL__TABLE 


Request and specify /BRIEF /NOCROSS__REFERENCE 
the contents of a /[NO]JCROSS__REFERENCE 
memory allocation /FULL /NOMAP (interactive) 

listing. /[NOJMAP /MAP=name.MAP (batch) where name 
is the name of the first input file. 





Specify the amount /(NOJ|DEBUG /NODEBUG 
of debugging infor- /[NOITRACEBACK /TRACEBACK 


mation. 


Indicate that input /JINCLUDE=(module-name....) 
files are libraries /LIBRARY 

and to specifically /SELECTIVE__SEARCH 
include certain mod- ; 

ules. 


Request or disablé /(NOISYSLIB /SYSLIB 

the searching of de- /INOISYSSHR /SYSSHR 

fault user libraries /[NOJUSERLIBRARY [=table] /USERLIBRARY=ALL 
and system libraries. 


Indicate that an in- /OPTIONS 
put file is a linker 
options file. 





3.2.1 Linker Messages 


If the linker detects any errors while linking object modules, it displays 
messages indicating the cause and severity of the error. If any error or fatal 
error conditions occur, that is, errors with severities of E or F, the linker does 
not produce an image file. 


The messages produced by the linker are descriptive, and you do not normally 
need additional information to determine the specific error. Some of the more 
common errors that occur during linking are as follows: 


e An object module has compilation errors. This error occurs when you 
attempt to link a module that had warnings or errors during compilation. 
You can often link compiled modules for which the compiler flagged warn- 
ings, but you should verify that the modules will actually produce the out- 
put you expect. 


¢ The modules that are being linked define more than one transfer address. 
The linker generates a warning if more than one module has an entry point 
designated with the OPTIONS (MAIN) keywords. The image file created 
by the linker in this case can be run; the entry point to which control is 
transferred is the first one that the linker found. 


Linking Programs 3-3 


This LINK command links the object module METRIC.OBJ with the mod- 
ules PRINTLINE and TERMLINE from the library FORMATS.OLB. Any 
references to external procedures and variables that are not defined in any of 
these three modules will cause the linker to search the library 
MATHLIB.OLB, in the directory [PROJECT.OBJLIB], before it searches the 
system libraries. 


The format and content of a linker options file are described in detail in the 
VAX-11 Linker Reference Manual. You may wish to use an options file if you 
have a very long list of input files to specify, if you want to link a module with 
a shareable image file, or if you want to request special linker options. 


When you specify more than one input file for the LINK command, the linker 
combines individual object files or modules explicitly included from a library 
in the order in which they are listed. 


3.2.3 Linker Output Files 


When you enter the LINK command interactively and do not specify any 
qualifiers, the linker creates only an executable image file. By default, the 
image file has the same file name as the first, or only, object module specified 
and a file type of EXE. For example: 


& LINK A+B;-C 


This LINK command links the object modules in the files A.OBJ, B.OBJ, and 
C.OBJ and creates the image file A.LEXE. 


In a batch job, the linker creates both an executable image file and a storage 
map file by default. The default file type for map files is MAP. 


Some of the rules for naming input and output files are shown in Table 3-2. 
These rules apply to the specification of names with the /MAP qualifier as 
well. 


Table 3-2: Specifying Input and Output Files for the Linker 





Example Output File(s) 


If you do not specify the}$ LINK METRIC METRIC.EXE 
/EXECUTABLE qualifier, the 

linker gives the image file the 

same name as the first input 

file. 

If you specify /EXECUTABLE/$ LINK METRIC,APPLIC/EXECUTABLE APPLIC.EXE 
following the name of an input 

file, the linker uses that file’s 


name to name the output file. 


If you give a file specification |$ LINK/EXECUTABLE=TEST METRIC,APPLIC | TEST.EXE 

with the /EXECUTABLE 

qualifier, the linker uses that 

file specification. 

When you specify a device}$ LINK METRIC,- [PROJECT.OBJLIBJFORMATS.EXE 
and/or directory for a file speci- | $__[PROJECT.OBJLIBJMATHLIB/LIBRARY,- 

fication, that device and/or di-|$__FORMATS : “‘UTABLE 

rectory becomes a temporary 

default for the remaining input 

and output files. 
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3.2.5 Specifying Debugging Qualifiers 


You can specify either the /DEBUG or /TRACEBACK saultaets when you 
link an image. These qualifiers control the amount of debugging information 
that is available to the VAX-11 Symbolic Debugger and to the run-time error 
reporting mechanism. 


By default, the linker includes traceback information. This information lets 
the run-time system list all of the active procedure invocations at the time of a 
fatal run-time error. If you specify the /NOTRACEBACK qualifier, that infor- 
mation will not be available. 


Regardless of whether you specified /DEBUG to the PL/I compiler, you can 
specify /DEBUG when you link the object module. This qualifier requests that 
the object modules containing the debugger program be linked to your object 
modules. When you execute the program, the debugger initially takes control. 
The steps required to run a program under the control of the debugger and the 
symbolic debugging capabilities available for PL/I programmers are described 
in the VAX-11 PL/I Guide to Program Debugging. 


3.3 Object Module Libraries 


An object module library is a single file containing individual object modules 
and two tables that index the modules: 


1. A module name table lists the names of the modules in the library. These 
are the names given to the modules when they are compiled. 


2. A global symbol table lists all global symbols defined in each module. 
These are the tables that are searched by the linker. 


3.3.1 Creating an Object Module Library 


The LIBRARY command creates and updates libraries. It assumes by default 
that a library upon which it is performing a function is an object module 
library. You can use object module libraries to: 


e Catalog and group together commonly used subroutines and functions. 


e Provide a default set of modules for the linker to use in resolving global 
references in object modules it is linking. 


e Enhance the performance of linking operations by putting all needed 
modules in a single library, thus reducing the number of files that need be 
opened during the linking. 


Figure 3-2 illustrates the sequence of creating object modules, creating a 
library, and using the library in linking programs. 
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The LIBRARY command uses the following default file types: 

e An object module library file is assumed to have a file type of OLB. 

e An object module file is assumed to have a file type of OBJ. 

When the LIBRARY command inserts an object module in a library, it: 
e Enters the name of the module in the library’s module name table. 


e Enters all global symbols from the object module, including the names of all 
entry points and all variables designated as global symbols, in the library’s 
global symbol table. 


For example, a PL/I program named QUEUES.PLI might contain the follow- 
ing designations: 


READY: PROCEDURE; 
ADDEL: ENTRY (QUEUE,POINTER); 


REMVEL: ENTRY (QUEUE,POINTER); 


This module can be compiled and placed in a library as follows: 


# PLI QUEUES 
# LIBRARY/INSERT DEFLIB QUEUES 


After this LIBRARY command, the module name table for the library 
DEFLIB.OLB contains an entry for the module named READY. The library’s 
global symbol table contains entries for the names ADDEL, REMVEL, and 
READY. Object modules that refer to any of these names can be linked with 
this library. When the library is specified as input to the linker, the linker 
searches the library's module name table and global symbol table for 
unresolved references. 


3.3.2 Defining the Search Order for Libraries 


When you specify libraries as input for the linker, you can specify as many as 
you wish; there is no practical limit. More than one library can contain a 
definition for the same module name. The linker uses the following conven- 
tions to search libraries specified in the command string: 


e A library is searched only for definitions that are unresolved in the previous 
input files specified. 


e If more than one library is specified for an object module, the libraries are 
searched in the order in which they are specified. 


For example: 
$ LINK METRIC +DEFLIB/LIBRARY +APPLIC 
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2. The process, then group, and then system logical name tables are searched 
for the name LNK$LIBRARY__1. If the logical name exists in any of these 
tables, and if it contains the desired reference, the search is ended. 


This search sequence is taken for each reference that remains unresolved. 


The search order can be modified for a particular link operation. To override 
the search of a library, you can do one of the following: 


e Delete the logical name assignment for the library you do not want 
searched. For example: 


# DEASSIGON LNK&LIBRARY 


The DEASSIGN command deletes the logical name table entry 
LNK$LIBRARY. 


e Specify /USERLIBRARY or /NOUSERLIBRARY on the LINK command. 
These qualifiers let you specify the PROCESS, GROUP, and SYSTEM 
keyword options to explicitly control which logical name tables are to be 
searched for default user libraries. For example: 


& LINK/USERLIBRARY=GROUP ineut-filerse:: 
When it executes this command, the linker searches only the GROUP 


logical name table. Specify /NOUSERLIBRARY to exclude all default user 
libraries in the search. | 


For complete details on defining and using default user libraries, see the 
VAX-11 Linker Reference Manual. 


3.3.4 System Libraries 


The directory identified by the system-defined logical name SYS$LIBRARY 
contains the library files: 


e VMSRTL.EXE 
e STARLET.OLB 


The file VMSRTL.EXE contains the VAX-11 Run-Time Library. The proce- 
dures in this library provide: 


¢ Commonly used mathematical and string-handling functions 
e Procedures that support code produced by VAX/VMS compilers 


VMSRTL.EXE is a library in shareable image format; that is, it is prelinked 
and can be accessed by many images concurrently. The procedures in a share- 
able image library can be used by a program even though the procedures 
are not physically included in the program image; the references to the proce- 
dures in the shareable image library are not resolved until the program is 
actually run. For information about creating shareable image libraries, and a 
description of the VAX-11 Run-Time Library, see the VAX-11 Run-Time 
Library Reference Manual. 


STARLET.OLB contains, in object module form, all the procedures in 
VMSRTL.EXE, as well as additional run-time modules required by various 
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Chapter 4 
Running PL/I Programs on VAX/VMS 


This chapter describes the following considerations for executing your PL/I 
programs on the VAX/VMS operating system. 


e Using the RUN command to execute programs interactively 

e Passing status values to the command interpreter 

e Executing programs in command procedures and batch jobs 

e Passing arguments to a PL/I program from a DCL command string 


For further information on any of the DCL commands or topics presented in 
this chapter, see the VAX/VMS Command Language User’s Guide. 


4.1 The RUN Command 


You execute a PL/I program with the RUN command. The RUN command 
assumes by default that the file type of a program image is EXE, so you need 
not specify it. For example: 


$ RUN METRIC 


This RUN command locates the file METRIC.EXE in the current default 
directory. It then gives control to the main entry point, that is, the entry point 
designated with the OPTIONS (MAIN) keywords on its PROCEDURE or 
ENTRY statement. If no procedure specifies OPTIONS(MAIN), then control 
is given to the first, or only, module in the image. 


4.1.1 Image Exit 


When the main procedure executes a RETURN or END statement, or when 
any procedure in the program executes a STOP statement, the image is termi- 
nated. In the context of the VAX/VMS operating system, the termination of 
an image, or image exit, causes the system to perform a variety of clean-up 
operations during which open files are closed, system resources are freed, and 
so on. 
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Table 4-1: Effects of FINISH Condition 


Procedure Procedure 
Has MAIN Has FINISH -.  Aetion When Image 
Option ON-unit Exit Occurs 


1 


The FINISH ON-unit is executed. If the ON-unit does 
not execute a nonlocal GOTO, the program terminates 
after the ON-unit executes. 


The program terminates normally.” 


The FINISH ON-unit is executed. If the ON-unit does 
not execute a nonlocal GOTO, the program terminates 
following the ON-unit. 


The image exits.” 





1. If the FINISH condition is signaled by the PL/I default condition handler following an 
ERROR condition, no FINISH ON-unit is executed. 

2. If the program is executed under control of the VAX-11 Symbolic Debugger, the Debugger 
displays the PL/I FINISH message. 


If there is a default PL/I condition handler, the message describes the error 
that occurred in PL/I terms. Otherwise, the message describes the error in 
VAX/VMS system terms. 


In either case, the message is followed by a traceback. For each module that 
has traceback information, the default handler lists the procedures that were 
active when the error occurred and the sequence in which the procedures were 
called, that is, the order of block activation. 


For example, if an integer divide-by-zero condition occurs, and no ON-unit for 
this condition exists in any active procedure block, the following run-time 
messages appear: 

%PLI-F-ERROR+ PL/I ERROR condition signaled 


ASYSTEM-F-FLTBIV +s arithmetic trap: floatinag/decimal divide 
by Zero at PC=O00007C4, PSL=O3C00045 


This message is followed by a traceback message as in the following example: 


BTRACE-F-TRACEBACK: symbolic stack dump follows 
module name routine name line Rekae aus Cae” See 
SETUP DIVIDE 5 OoOoGaGG0 7 él 

SETUP BEGING@4 él OoOoOCGoORS 

SETUP SETUP Fa HoGoooocr 

LIBS NEXT 14 oooogddd 

LIBS LIBS 15 oOoOogdgoaAC 





These columns provide information as described below. 


module name 
Indicates the name of a level-one procedure that was active when the error 
occurred. 


The first module name is the name of the module in which the error oc- 
curred. Each subsequent line gives the name of the caller of the procedure 
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This command interrupts the program APPLIC. After you have interrupted a 
command, you can cause it to terminate by entering a DCL command that 
causes another image to be executed or by entering the DCL command EXIT. 
In this case, PL/I signals the FINISH condition to allow a FINISH ON-unit to 
execute before the given DCL command is executed. 


Following a CTRL/Y interruption, you can also force an entry to the debugger 
by entering the DEBUG command. The debugger is described in the VAX-11 
PL/I Guide to Program Debugging. 


There are some. other DCL commands you can enter that have no direct effect 
on the image. You can use these commands and resume the execution of the 
image with the DCL command CONTINUE. For example: 


€ RUN APPLIC 
ad 


# SHOW TRANSLATION INFILE 


INFILE = (undefined) 
# DEFINE INFILE DBAL:CTESTFILESI] JANUARY .DAT 
# CONTINUE 


In this example, interrupts the image APPLIC. The SHOW TRANSLA- 
TION command indicates that no equivalence name is present for the logical 
name INFILE. The DEFINE command establishes an equivalence for the 
name and the CONTINUE command resumes the program. 


For a complete list of the commands you can enter following a interrup- 
tion without affecting the current image, see the VAX/VMS Command Lan- 
guage User’s Guide. 


In most cases, the effect of and on a program is the same. How- 
ever, some programs (including programs you may write) establish particular 
actions to take to respond to CtRilc). If a program has no @tRLc) handling rou- 
tine, then is the same as and in fact is echoed as “Y on the 
terminal. For information on writing a routine for a PL/I program, see 
Section 19.4.4, “A CTRL/C Handling Routine.”’ 


4.2 Returning Status Values to the Command Interpreter 


You can define a main procedure to be executed under the control of the DCL 
command interpreter as a PL/I function. Then the RETURN statement can 
specify a status value to be used as a success, failure, or informational indica- 
tor to the command interpreter. For example: 


TESTP: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY(31)335 


RETURN (€ualued; 


where the value specified on the RETURN statement can be any constant, 
variable, or expression that can be converted to a fixed-point binary value. 
For meaningful results, you must specify the returns descriptor on the RE- 
TURNS option for the PROCEDURE statement as FIXED BINARY (381). 


When any program or command is executed under the control of the DCL 
command interpreter, the general register RO, by convention, indicates the 
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4.3 Using Command Procedures 


A command procedure is a file that contains a sequence of VAX/VMS com- 
mands and, optionally, data. You can cause the commands in the procedure 
to be executed in either of two ways: 


e Interactively, you specify the name of the file following the @ (Execute 
Procedure) command. For example: 


$ @TESTAM 


The @ command assumes that the file type of a command procedure is 
COM. This command executes the procedure TESTAM.COM. 


e You can submit the command procedure to a system batch job queue for 
execution. After the job completes, the system prints a log file that indicates 
how the job ran. The SUBMIT command submits a job. For example: 


$¢ SUBMIT TESTAM 


This command enters the file TESTAM.COM to the system batch job 
queue. 


You can devise and use command procedures to simplify and enhance your 
program development. For example, you can write a command procedure that 
will compile, link, and run a specific PL/I program. The command procedure 
can specify all the needed libraries for the PLI and LINK commands, and can 
even contain all the input data you would require to test the program. 


Command procedures can also be generalized. By taking advantage of DCL 
commands such as the assignment statement, and the IF, GOTO, and ON 
commands, you can write a command procedure that looks like a PL/I pro- 
gram: it can process variables, make decisions based on their values, and 
perform error condition handling. . 


The example in Figure 4-1 shows a simple procedure that will give you an idea 
of how to construct and use command procedures to help you with your PL/I 
program development and testing. 
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6. The program APPLIC is exécuted. It reads input data from the default 
input device. When a command procedure executes, the default input 
device is the command procedure itself. Thus, the data is read from the 
procedure file. In a command procedure, any line that does not begin with 
a dollar sign is treated as input data for the previous command or pro- 
gram. Program input terminates (and an actual end-of-file condition oc- 
curs) when a line that begins with a dollar sign is read. In this example, 
the program APPLIC reads all the lines between the RUN command and 
the EXIT command. | 


For more detailed information on the commands shown above, and for addi- 
tional examples of techniques you can use in command procedures, see the 
VAX/VMS Guide to Using Command Procedures. 


4.4 Passing Data to a Main Procedure 


The VAX/VMS command interpreter does not provide an explicit interface 
for passing arguments to a main program. There are, however, programming 
techniques that permit you to pass data at run time to affect the execution of 
a program. This section describes the following techniques: 


e Defining the program as a foreign DCL command and specifying data on the 
command line that invokes the program 


e Using logical names as program arguments 
Both of these techniques are restricted to character-string arguments. 


The examples in the sections that follow provide enough information for you 
to duplicate them. Where appropriate, the text refers to additional required 
conceptual information found elsewhere in this manual. 


4.4.1 Passing Data from the Command Line 


When any command is executed on the VAX/VMS system, the command 
interpreter stores a copy of the command in an internal buffer. You can access 
the data in this buffer from a PL/I program by coding a call to.a run-time 
library procedure named LIB$GET_FOREIGN. To use this routine, there are 
two things you must do: | 


1. To pass data to a program when it is run, you must use a DCL assignment 
command to equate a command symbol to a foreign command name. The 
command name will be used instead of a RUN command to execute the 
program image. 


2. To obtain the data, the program must call a run-time library procedure to 
obtain the command string and must perform all string parsing and analy- 
sis itself. 


Each of these mechanisms is described in detail on the following pages. 
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Sample Program 4-1: Obtaining the Command Line from the Command 
Interpreter 


GETLINE: PROCEDURE OPTIONS(MAIN) 
YINCLUDE #STSDEFI@ 


DECLARE LIBSGET.FOREIGN EXTERNAL ENTRY ¢ 2) 
CHARACTER(#) » /* BUFFER TO RECEIVE COMMAND STRING #/ 
CHARACTER(C#) + /* PROMPT STRING: IF ANY #/ 
FIXED BIN(15)) ¢# LENGTH OF COMMAND STRING #/ 
RETURNS (FIXED BINARY (31333 


DECLARE COMMAND_LSTRING CHARACTER(300}+ /# OUTPUT BUFFER #/ 
@ RETURN-LENGTH FIXED BINARY( 13) + /# QUTPUT LENGTH #/ 
PROMPTOUSTRING CHARACTER(C12) STATIC INITIAL( ‘Enter Lines ‘(33 


STS$VALUE = LIBSGET.FOREIGN( COMMAND STRING; 

PROMPTUSTRING + 

0 RETURNOLENGTH) 3 
IF “STS$SUCCESS THEN GOTO ERRORS 


e PUT SKIP LIST(SUBSTR (COMMAND USTRING+:1;-RETURNOLENGTH?) 33 


RETURN 5 

ERKOR: 
PUT SKIP LIST(’ERROR IN LIBSGET_FOREIGN’)$ 
RETURN 

END 4 


The following notes are keyed to Sample Program 4-1: 


1. The procedure includes the module $STSDEF from the default INCLUDE 
library PLISYSDEF.TLB. This module contains the declarations for the 
variables STS$VALUE and STS$SUCCESS, which are used to test 
whether the procedure LIBSGET_FOREIGN completed successfully: 


2. LIB$GET_FOREIGN has three parameters: an output buffer, an op- 
tional prompt string, and a variable to receive the length of the string 
returned in the output buffer. 


These parameters are declared in the entry declaration. The parameter 
descriptors for the character-string parameters must be declared as 


CHARACTER(*). 


3. The corresponding arguments for the prowediire’s: fhitee parameters are 
COMMAND_STRING, PROMPT_STRING, and RETURN 
LENGTH, respectively. 


4, LIB$GET__FOREIGN is invoked as a function so that its return value can 
be tested. The function reference returns the status into the variable 
STS$VALUE. The variable STS$SUCCESS is a one-bit field based on 
the low-order bit of STS$VALUE. This bit, if true, indicates a successful 
return. 
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Logical names and equivalence names are each limited to 63 alphanumeric 
characters, including dollar signs ($) and underline characters (__). Uppercase 
and lowercase letters are not equivalent. For example, the following com- 
mands would result in different equivalence names: 


$ DEFINE NAME MABEL 
$ DEFINE NAME "Mabel" 


Note that the command interpreter translates all strings that are not enclosed 
in quotation marks to uppercase. 


You can specify numeric character strings for integer arguments. For exam- 
ple, to define an equivalence name for the logical name NUMBER_OF_ 
ITERATIONS, you could specify: 


$ DEFINE NUMBER_OF_ITERATIONS 10 


Note that the program that translates this name must perform an explicit 
conversion of the character-string value to an arithmetic data item. 


4.4.2.2 Translating Logical Name Arguments — A procedure that interprets a 
logical name argument must explicitly translate the logical name by invoking 
the SYS$TRNLOG system procedure. This procedure is in the default system 
object module library, and will be automatically located when you link a 
program that references it. 


This procedure has the following parameters: 


1. A CHARACTER(*) parameter that represents the logical name string to 
be translated. 


2. A FIXED BINARY(15) parameter in which the procedure places the 
length of the resultant equivalence name string. 


3. A CHARACTER(*) parameter in which the procedure places the trans- 
lated equivalence name string. 


4. Three optional parameters for which the procedure provides default val- 
ues. These parameters are of no interest in this example and may be 
omitted. 


The program PRINT_.NAME in Sample Program 4-2 illustrates a main pro- 
cedure that translates the logical names NAME and NUMBER_OF_ 
ITERATIONS and uses the resulting equivalence name strings. 
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The following notes are keyed to Sample Program 4-2: 


1; 


The procedure includes the INCLUDE modules SYS$TRNLOG and 
$STSDEF. These modules are in the PL/I default INCLUDE library 
PLISYSDEF.TLB; they contain the declarations of the SYS$TRNLOG 
system service and the variables STS$VALUE and STS$SUCCESS, 
which are used to test whether the system service call completed success- 
fully. 


For each logical name, the procedure declares a string initialized to the 
logical name value, an output string variable, and an output length varia- 
ble. 


The integer variable ITERATION_COUNT is used in the conversion | 
of the character-string equivalence name returned for the logical name 


NUMBER__OF_ITERATIONS. 


SYS$TRNLOG is invoked as a function so that its return status can be 
tested. 


The trailing commas in the argument list indicate arguments that are not 
specified — the SYS$TRNLOG system service provides default values for 
these arguments. The commas must, however, be specified. For details on 
omitting optional arguments to procedures, see Section 14.5.2, “Optional 
Arguments.” 


The function reference returns the status into the variable STS$VALUE. 
The variable STS$SUCCESS is a one-bit field based on the low-order bit 
of STS$VALUE. This bit, if set to 1, indicates a successful return. 


If either call to SYS$TRNLOG is not successful, the procedure exits. For 
complete details on testing return status values, and a description of the 
variables STS$VALUE and STS$SUCCKESS, see Chapter 16, “Return 


Status Values.” 


The variable ITERATION_COUNT is assigned a value using the 
SUBSTR built-in function, which extracts the valid portion of the equiva- 
lence string from the 63-character equivalence name. This value is used to 
control the execution of the DO-group that follows. 


Note that the SYS$TRNLOG procedure returns a successful status if a 
logical name is not defined; thus, the results are unpredictable (and usu- 
ally cause an error) if the procedure does not explicitly test the return 
status to see if a name was translated. 
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Part IT 
The File System 


Chapter 5 
Overview of the File System 


This chapter introduces aspects of the VAX/VMS operating system that re- 
late to PL/I input and output. It describes: 


e The relationship between PL/I input/output statements and VAX/VMS 
input/output procedures 


e File-naming and definition conventions, including a description of 
VAX/VMS logical names and process permanent files 


e File system error handling at run time 


e ENVIRONMENT options for input/output optimization 


5.1 Relationship of PL/I 1/O to the VAX/VMS File System 


When a PL/I program contains an input/output statement, for example, 
OPEN or READ, the compiler translates the request into a call to the appro- 
priate VAX/VMS operating system procedure. 


In the VAX/VMS system, input/output is performed by: 


e VAX-11 Record Management Services (RMS). RMS provides complete file 
and record-handling capabilities. 


¢ Input/output system services. System services provide direct control over 
data transfer between the process executing an image and a peripheral 
device. 


Note that although it is possible to call RMS procedures and VAX/VMS 
system services directly from a PL/I program, it is not normally necessary to 
do so. A PL/I program executed on the VAX/VMS operating system has full 
access to RMS capabilities through: 


e Options of the ENVIRONMENT attribute 
e Keyword options on PL/I input/output statements 
e Built-in subroutines that invoke RMS file-handling services 


RMS, in turn, manages the details of communicating with the VAX/VMS I/O 
system to effect data transfer and to organize and arrange data on physical 
devices. 
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2. It supplies missing fields from the value specified in the DEFAULT_ 
FILE_NAME option of the ENVIRONMENT attribute, if that option is 
specified. 


3. It then applies system defaults to complete the file specification. 


If the file specification that is finally achieved is invalid (for example, if it 
contains a dollar sign or underline character) or represents an illegal device or 
file (for example, if an input file cannot be found), the UNDEFINEDFILE 
condition is signaled. 


The actions that PL/I and the file system take for each of these steps are 
described in more detail in the following sections. 


5.2.2 Using Logical Names 


At the command level before executing a program, you can create a logical 
name to assign a VAX/VMS file specification to the identifier of a PL/I file 
constant or to a value specified in a TITLE option. For example, suppose a 
PL/I program declares and opens a file as follows: 


DECLARE INFILE FILE: 


OPEN FILE (INFILE) RECORD INPUTS 


You associate a VAX/VMS file with the identifier INFILE as in this example: 
# DEFINE INFILE DBi:C€TEMP1A.DAT 


The DEFINE command gives the PL/I file INFILE the VAX/VMS file equiva- 
lent of DB1:[TEMP]A.DAT. In VAX/VMS terms, the name INFILE is a 
logical name and the name DB1:[TEMP]A.DAT is an equivalence name for 
the logical name. 


You can also use the DEFINE command to specify alternate device or file 
equivalents for the PL/I default file constants SYSIN and SYSPRINT. For 
example, to redirect output for the default file SYSPRINT, you could specify 
a command as follows: 


$ DEFINE SYSPRINT TEST.OUT 


While this assignment is in effect, any PL/I procedure that outputs data to 
SYSPRINT (without opening SYSPRINT with an explicit title) will create a 
file named TEST.OUT on the current default device. 


Logical names may also be established by other commands. For example, you 
can specify a logical name for a device when you enter an ALLOCATE or | 
MOUNT command while placing the device on line. For example: 
$ ALLOCATE 
# Devices MT: 
$#.LogwNames:s INFILE 

-MTA1: ALLOCATED 


This ALLOCATE command allocates a tape drive and establishes the logical 
name INFILE for it. When a PL/I program reads from the file INFILE, the 
system will translate the name INFILE and use the tape MTAI1: as the input 
device. 
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System logical 
name table 


PAY_DEV DBB2:' 
WEEKLY_UPDATE PAY__DEV:[WEEKLY.BACKUP]WEEK42. DAT? 


OUTFILE WEEKLY__UPDATE® 


1. This assignment may have been made when a disk 

volume was placed on line with a command, as follows: 

$ MOUNT/SYSTEM DBB2: 

$ Label: PAYROLL__FILES 

$ Log_Name: PAY_DEV 
2. This assignment may have been made as follows: 

$ DEFINE/GROUP WEEKLY_UPDATE PAY__DEV:[WEEKLY.BACKUP]WEEK42.DAT 
3. This assignment may have been made as follows: 

$ DEFINE OUTFILE WEEKLY_.UPDATE 





Group logical 
name table 









Process logical 
name table 





OPEN FILE(OUTFILE) RECORD OUTPUT; 

To determine the file specification, the system: 

1. Translates the name OUTFILE. The result is: 
WEEKLY_UPDATE 


2. Translates the name WEEKLY_UPDATE. The result is: 
PAY _DEV:[WEEKLY.BACKUP]WEEK42.DAT 


3. Translates the name PAY__DEV. The final resulting 
tile specification is: 
DBB2:[WEEKLY.BACKUP]WEEK42.DAT 


Figure 5-1: Translating Logical Names 


5.2.2.2 Process Permanent Logical Names — The system provides every user 
and every batch job with a default set of process logical name table assign- 
ments. These logical names are listed in Table 5-1. Because the files associ- 
ated with these assignments exist for the life of the process, or job, and 
because they are permanently open, they are called process permanent files. 
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e The equivalence name for the logical name REPORT does not contain a file 
type. In this case, the file type LIS will be supplied by default to the 
translated equivalence of the logical name REPORT. 


VAX-11 PL/I uses the punctuation in the DEFAULT_FILE_NAME option 
to determine which portion of the file specification is specified. Thus, the 
period (.) in the above example indicates that the value is a file type. An 
unpunctuated name is treated as a file name; a name terminated by a colon 
(:) is treated as a device name (and can therefore be a logical name). 


When the DEFAULT_FILE_NAME option is not specified for a file, PL/I 
supplies a default value for the option of ‘““.DAT”’’; that is, PL/I applies the file 
type DAT to a file specification that does not have a file type. 


PL/I applies the value of the DEFAULT_FILE_NAME option after it estab- 
lishes the file’s title. Thus, in the preceding example, the title, REPORT, is 
established before the value ‘‘.LIS”’ is applied. Note that the only time that a 
file name in a DEFAULT_FILE_NAME option is used is when the TITLE 
option specifies a null string; that is, the TITLE option is specified as: 
TITLE(’ 4) 


A DEFAULT_FILE_NAME option can specify any portion of a file specifi- 
cation. For example: © 


DECLARE REMOTE_FILE FILE RECORD INPUT 
ENW (DEFAULT FILENAME ¢ 
‘RONDO::DBB2:CMALCOLM].TXT‘3)3 
This option specifies a node name, device, directory, and file type. The file 
name must be supplied when the file is opened. For example: 


OPEN PELE CREMOFECFILE): TITLE C*ALLEGRIT* ):s 


This OPEN statement opens the file: 
RONDO: :0BB2: [MALCOLMIALLEGRO. TXT 


Another OPEN statement for the file may specify a different TITLE option, 
for example, TITLE(’ ANDANTE’), to open a different file. Note that if no 
TITLE option is specified in this example, the UNDEFINEDFILE condition 
will be signaled because the default title, REMOTE_FILE, is an invalid 
VAX/VMS file name. 


5.2.4 Expanding File Specifications 


After logical name translation and after values supplied by the DEFAULT_ 
FILE_NAME option, if any, are applied, the defaults that the file system 
applies are as follows: 


Field System Default Provided 
node Local system 

device Current default device 
directory Current default directory 
file name None 

file type DAT 


version number _ For an input file, the most recent version; for an out- 
put file, the highest existing version number, plus 1. 
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Example: 


DCL STATES FILE RECORD OQUTPUTs 
OPEN FILE (STATES) 5 


Steps: 
1. Apply the default title, STATES. 


2. Translate the logical name STATES to obtain the equivalence name, 
DMA2:[BACKUP]. 


3. Apply default file type DAT and the default version number (for an out- 
put file). Note that no default is supplied for the file name. 


Final Specification: DMA2:[BACKUP].DAT;n where n is one higher than 
the number of any existing version of the file 


Example: 


DCL TAPEFILE FILE RECORD ENYWIRONMENT ¢ 
DEFAULT FILE_NAME( ‘TAPEFILE: ’))3 
OPEN FILECTAPEFILE? OUTPUT TITLE(‘TAPEIL-FIL ‘33 


Steps: 
1. Apply the title TAPE1.FIL. 


2. Translate the name TAPEFILE in the DEFAULT__FILE_ NAME option 
to its equivalence, MTAO:. 


3. Use the system default version number for tape files, 0. Tape files do not 
have directories. 


Final Specification: MTA0:TAPE1.FIL;0 


5.3 Error Handling 


VAX-11 PL/I uses the standard PL/I ON condition names to signal run-time 
errors that occur for file operations. The ON conditions that are signaled, and 
the circumstances under which they are signaled, are: 


e The UNDEFINEDFILE condition is signaled whenever a file cannot be 
opened. 


¢ The ENDFILE condition is signaled when the end-of-file is reached during 
an input operation. 


¢ The ENDPAGE condition is signaled for a file with the PRINT attribute 
when the current line number exceeds the page size specified for the file. 


e The KEY condition is signaled for a file with the KEYED attribute when 
any error involving the interpretation, writing, or specification of a key 
occurs. | | 


e The ERROR condition is signaled for all other file-related errors. 
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5.3.2 Default Error Handling 


If a file system error occurs during the execution of a PL/I statement, the PL/I 
run-time system signals either the specific PL/I condition name or the 
ERROR condition. If no user-specified ON-units exist to handle either the 
specific PL/I condition or the ERROR condition, PL/I performs its default 
condition handling. 


If any active procedure specified OPTIONS(MAIN), a default PL/I ON-unit 
is present and executed. The default PL/I ON-unit prints a PL/I run-time 
error message. If the default PL/I ON-unit is not present, the error signal is 
passed to the default condition handler established by VAX/VMS, which 
prints the message associated with the RMS error. If the error was a fatal 
error, the handler terminates the program; otherwise, the program continues. 


The following example illustrates the type of messages that the PL/I run-time 
system displays when an error occurs during an I/O operation: 


“PLI-F-ERROR+ PL/I ERROR condition. 
~PLI-I-IQERROR: I/O error an file ‘“STATELWFILE’ 








~PLIT-~I-FILENAME: File name: “DB? :LMALCOLMISTDATA. DAT = ° 
~PLI-~I-NOTRKEYD;: Not a KEYED file. 

&TRACE-F-TRACEBACK + symbolic stack dume follows 

module name POuULLNS name line Telative PC absolute PC 
PLISCONDIT $CODE OoOagggagS NLPAG 
PLISFREAB €COBe oc = 

FLOWERS BEGINZAGS 35 fe 

FLOWERS BEGINZSS 2 Oe 5 

FLOWERS FLOWERS ao COG a OOOoOORAS 


In this example, the error occurred because a keyed I/O statement was speci- 
fied for a file that does not have the KEYED attribute. For an explanation of 
the information in a traceback message, see Section 4.1.2, “Run-Time Er- 
rors.” 


5.4 Input/Output Optimization 


Many of the VAX-11 PL/I options for the ENVIRONMENT attribute provide 
optimization features for input/output operations. Table 5-2 summarizes the 
options that control disk file allocation. These options let you specify the 
space requirements of a file when you create it. Table 5-3 summarizes the 
options for run-time optimization of input/output processing. All options are 
described in detail in Chapter 6, “ENVIRONMENT Options.” 
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Chapter 6 
Options of the ENVIRONMENT Attribute 


The options to the ENVIRONMENT attribute provided by VAX-11 PL/I let 
you: 


e Describe the attributes of a file when it is created 


e Request special processing and optimization options when the file is being 
read or written 


e Specify the disposition of a file when it is closed 


Most of the options for the ENVIRONMENT attribute correspond directly to 
RMS options and control values. PL/I, in some cases, provides different de- 
faults than does RMS. 


This chapter presents an overview of the ENVIRONMENT options and infor- 
mation on how to specify them and gives a reference description of each 
option. The descriptions of the ENVIRONMENT options begin in Section 
6.2.1, and are arranged in alphabetic order. 


6.1 Specifying and Using ENVIRONMENT Options 


All ENVIRONMENT options may be specified in the declaration of a file 
constant or in an OPEN statement to open a file. Certain options may also be 
specified in a CLOSE statement. 


6.1.1 Arguments for ENVIRONMENT Options 


ENVIRONMENT options may be grouped in the following categories, based 
on whether they require an argument and what type of argument is required: 


e Many options require you to specify an expression representing a value to 
override a default value provided by VAX-11 PL/I. | 


e A few ENVIRONMENT options require you to provide a reference to a 
variable that either contains information pertaining to the open or that will 
receive information when the related file is opened. 


e All options that are not in one of the above categories may be specified with 
a Boolean expression that enables or disables the option. If no value is 
specified with an option, the option is enabled. 
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6.1.2 Interpretation of ENVIRONMENT Options for Existing Files 


Many ENVIRONMENT options specify values that can be set only when a 
file is created. For example, the length of records in a file with fixed-length 
records is set when the file is created and cannot be changed thereafter. When 
these options are specified for a file, they are applied to the file only if the 
open of the file actually results in the creation of a new file. If the open results 
in the opening of a file that already exists, the option is ignored. 


6.1.3 Determining ENVIRONMENT Options 


A PL/I program can determine the value or setting of an ENVIRONMENT 
option at run time for an indicated file by calling the DISPLAY built-in 
subroutine. This built-in subroutine returns information about a specified 
PL/I file to a user-specified structure. The member names in the structure 
correspond to the keywords of the ENVIRONMENT attribute. 


For a description of the values returned by this subroutine, and an example of 
calling it, see Section 8.1, “DISPLAY Built-In Subroutine.”’ 


Certain ENVIRONMENT options themselves return information to the pro- 
gram when an existing file is opened. For example, the FIXED _CONTROL_ 
SIZE_TO option may be specified when an existing file with a fixed control 
area is opened. PL/I returns the size of the fixed control area to the program. 


6.1.4 Device Independence of ENVIRONMENT Options 


Many ENVIRONMENT options apply only to a particular type of device or 
to a specific file organization. For example, the REWIND _ON_CLOSE and 
REWIND__ON__OPEN options apply only to magnetic tape files, and the 
FILE__SIZE option applies only to disk files. 


When any ENVIRONMENT option is specified for a device to which the 
option does not apply, the option is ignored. 


6.1.5 Conflicting and Invalid ENVIRONMENT Options 


Conflicting or invalid options or values for options may be detected during 
compilation or at run time. At compile time, the compiler issues a diagnostic 
message to indicate the error. 


At run time, the UNDEFINEDFILE condition is signaled if conflicting op- 
tions are in effect or if conflicting values are specified for the same option. For 
example, if the FILE_SIZE option is specified in the DECLARE and OPEN 
statements for a given file and if the options specify different values, UNDE- 
FINEDFILE is signaled. 


For run-time errors, an ON-unit can reference the ONCODE built-in function 
to determine the specific error, if desired. If no ON-unit exists for the UNDE- 
FINEDFILE condition, the PL/I run-time system displays an error message 
describing the error that occurred. 
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Table 6-1: Summary of ENVIRONMENT Options 


APPEND 


BATCH 


BLOCK_-BOUNDARY__FORMAT 


BLOCK_IO 


BLOCK__SIZE(expression) 


BUCKET_SIZE(expression) 


CARRIAGE_RETURN__FORMAT 


CONTIGUOUS 


CONTIGUOUS__BEST_TRY 


CREATION__DATE (variable) 


CURRENT_POSITION 


Places output for a file at the end of an 
existing file. 


Submits a copy of the file to the sys- 
tem batch job queue on close. 


Indicates that records must not cross 
block boundaries. 


Specifies a file will be read or written 
by blocks instead of records. 


Specifies the size of a block for the cre- 
ation of a magnetic tape file. 


Defines the number of 512-byte blocks 
in a bucket for an indexed sequential 
or a relative file. 


Indicates that records in the file will 
be printed with default carriage con- 
trol. 


Specifies that an output file must be 
placed in a physically contiguous ex- 
tent on disk. 


Requests that if possible an output file 
be placed in a physically contiguous 
extent on disk. 


Overrides default creation date of file. 


Leaves magnetic tape positioned at 
last close. 


Specify 
At 


Create 
Open 


Create 
Open 
Close 
Create 
Create 
Open 


Create 


Create 


Create 


Create 


Create 


Create 


Create 
Open 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Record 


Record 


Stream 


Record 


Record 


Record 
Stream 


Record 
Stream 


Record 


Stream 


Record 


Stream 


Default 


Value 


Disabled 


Disabled 


Disabled 
Disabled 
Mount 
value 
Maximum 
record size 


Enabled 


Disabled 


Disabled 


Current 
date and 
time 


Disabled 


Data Type 


BIT(1) 


BIT(1) 


FIXED BINARY(31) 


FIXED BINARY(31) 


BIT (64) ALIGNED 


BIT(1) 





(Continued on next page) 
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Table 6-1(Cont.): 


INDEX—NUMBER(expression) 


INDEXED 


INITIAL_FILL 


MAXIMUM__RECORD__NUMBER (expression) 


MAXIMUM_RECORD__SIZE(expression) 


MULTIBLOCK__COUNT(expression) 


MULTIBUFFER__COUNT(expression) 


NO_SHARE 


OWNER_GROUP(expression) 


Summary of ENVIRONMENT Options 


Specifies the initial index to use in ac- 
cessing records in an indexed sequen- 
tial file. 


Defines an indexed sequential file. 


Requests the file system to leave 
unused space in file index overflow 
buckets. 


Specifies the largest record number 
that will be valid for records in a rela- 
tive file. 

Specifies the maximum size that is 
valid for any record in the file. 


Specifies the number of blocks to allo- 
cate for file system buffering. 


Specifies the number of buffers to allo- 
cate for file system buffering. 


Prohibits all type of shared access to 
the file. 


Specifies the group number in the user 
identification code (UIC) of the owner 
of the file. 


Specify 
At 


Create 
Open 


Create 
Open 


Open 


Create 


Create 
Open 


Create 
Open 


Create 
Open 


Create 


Record 


Record 


Record 


Record 


Record 


Record 


Record 


Record 


Record 
Stream 


*For sequential files with fixed-length records. For sequential files with variable-length records, the default is 510 


bytes. For relative files, the default is 480 bytes. 


+ Disabled if the file is opened for input, enabled if opened for output or update. 


Default 
Value 


Disabled 


Disabled 


512 bytes* 


Current 
process 
default 


Current 
process 
default 


+ 


Current 
process 
group 
number 


Data Type 


FIXED BINARY(31) 


BIT(1) 


BIT(1) 


FIXED BINARY(31) 


FIXED BINARY(31) 


FIXED BINARY(31) 


FIXED BINARY(31) 


BIT(1) 


FIXED BINARY(31) 





(Continued on next page) 
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Table 6-1(Cont.): 


* 


Option 


SCALARVARYING 


SHARED__READ 


SHARED__WRITE 


SPOOL 


SUPERSEDE 


SYSTEM_PROTECTION (expression) 


TEMPORARY 


TRUNCATE 


WORLD__PROTECTION (expression) 


WRITE_BEHIND 


WRITE_CHECK 


Summary of ENVIRONMENT Options 


Specifies that varying character 
strings will be read/written using the 
entire storage of the variable. 


Allows other users to read records in 
the file. 


Allows other users to read and write 
records in the file. 


Queues ‘a copy of the file to the system 
printer when the file is closed. 


Replaces an existing file with the same 
file name, file type, and version num- 
ber. 


Defines the type of file access allowed 
to users with system user identifica- 
tion codes. 


Specifies a temporary file for which no 
directory entry is made. 


Truncates a sequential file at its logi- 
cal end-of-file when it is closed. 


Specifies the type of file access al- 
lowed to general system users. 


Requests file system optimization on 
output operations. 


Requests verification of output opera- 
tions. 


Enabled if the file is opened for input, otherwise disabled. 


Specify 
At 


Create 
Open 


Create 
Open 


Create 
Open 


Create 
Open 
Close 


Create 


Create 


Create 


Create 
Update 
Close _ 


Create 


Record 


Record 


Record 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Record 
Stream 


Default 
Value 


Disabled 


Disabled 


Disabled 


Disabled 


Current 
process 
default 


Disabled 


Disabled 


Current 
process 
default 


Disabled 


Disabled 


Data Type 


BIT(1) 


BIT(1) 


BIT(1) 


BIT(1) 


BIT(1) 


CHAR(4) 


BIT(1) 


BIT(1) 


CHAR(4) 





mM Usage 


When you specify both the TEMPORARY and DELETE options in conjunc- 
tion with the BATCH option, the file is submitted to the batch job queue and 
marked for deletion after the batch job completes. 


6.2.3 BLOCK BOUNDARY_FORMAT Option 


The BLOCK_BOUNDARY-__FORMAT option indicates that records in the 
file must not cross block boundaries. 


The format of this option is: 
BLOCK._BOUNDARY__FORMAT | (boolean-expression) |] 


@ Rules 


1. The BLOCK.__BOUNDARY__FORMAT option is meaningful only when a 
file is created. 

2. This option applies only to sequential files; it is ignored if specified for 
relative or indexed sequential files. 


3. If the BLOCK_BOUNDARY_FORMAT option is specified for a file, the 
maximum record size must be less than 512 bytes. 


4, BLOCK_BOUNDARY_FORMAT conflicts with the BLOCK_IO op- 
tion. However, a file that is created with the BLOCK_BOUNDARY_ 
FORMAT option can later be read with the BLOCK _IO option. 


M@ Usage 


The BLOCK_BOUNDARY_FORMAT option can be paired with the 
CARRIAGE__RETURN_FORMAT or PRINTER_FORMAT option to de- 
fine the attributes of a file’s records. 


This option may be useful for the creation of files that will be read in terms of 
blocks. Note, however, that this option may result in unused disk space when 
records do not fill blocks. 


6.2.4 BLOCK_1!IO Option 


The BLOCK_IO option indicates that all I/O operations on the file will be in 
terms of physical blocks rather than records. In an I/O statement, a block is 
treated as if it were a single logical record. The format of this option is: 


BLOCK_IO [ (boolean-expression) |] 


@ Rules 


1. The BLOCK_IO option is meaningful when a file is created or opened. 
The file can be opened with any of the attributes INPUT, OUTPUT, or 
UPDATE. If the file is opened for output, the created file is always se- 
quential. 
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@ Rules 
1. The BLOCK_SIZE option is meaningful only when a file is created. 
2. This option is applied only to magnetic tape files. 


@ Usage 


When a tape file is opened with the BLOCK_IO option of ENVIRONMENT, 
the block size of the file is used to determine the number of bytes to be 
transferred in a single I/O operation. 


Tape file input/output is described in Section 10.2, “Using Magnetic Tape 
Files.” 


6.2.6 BUCKET_SIZE Option 


The BUCKET__SIZE option lets you specify the number of blocks to use for 
each bucket when you create a relative file. The BUCKET_SIZE option has 
the format: 


BUCKET_SIZE(integer-expression) 


integer-expression 
Is a fixed binary value in the range of 0 to 32, representing the number of 
blocks in each bucket. If the bucket size is specified as 0, or if it is not 
specified, PL/I applies the current RMS default. This default can be set 
with the DCL command SET RMS__DEFAULT; its current value can be 
determined with the command SHOW RMS_ DEFAULT. 


@ Rules : 
1. The BUCKET_SIZE option is meaningful only when a file is created. 


2. This option applies only to relative files. 


M@ Usage 


Selection of a bucket size for a relative file depends on the size of the records 
in the file. Although records within a bucket can cross block boundaries, 
records cannot cross bucket boundaries. Therefore, the number of blocks per 
bucket that you specify with this option must conform to one of the formulas 
given below. 
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By careful calculation of a bucket size, you can improve input/output opera- 
tions on the file. In general, a bucket size of between four and eight blocks 
results in good performance for most files. For detailed information on file 
design and space considerations, see the RMS-11 User’s Guide. 


6.2.7 CARRIAGE_RETURN_FORMAT Option 


The CARRIAGE_RETURN_FORMAT option indicates that each record in 
the file is to be preceded by a line feed and followed by a carriage return when 
the line is written to a carriage control device such as a terminal or line 
printer. The format of this option is: 


CARRIAGE__RETURN_FORMAT | (boolean-expression) | 


@ Rules 


1. The CARRIAGE_RETURN__FORMAT option is meaningful only when a 
file is created. 


2. CARRIAGE_RETURN conflicts with the PRINTER_FORMAT and 
BLOCK_1IO options and with the PRINT file description attribute. 


m@ Usage 
CARRIAGE_RETURN_FORMAT is the default format for record files. 


This type of carriage control is an attribute of the file that is known to the file 
system; it does not require space within the file’s records. 


6.2.8 CONTIGUOUS Option 


The CONTIGUOUS option specifies that disk space for the associated file 
must be allocated using contiguous blocks on the disk. The format of this 
option is: 


CONTIGUOUS [ (boolean-expression) ] 


@ Rules 
1. The CONTIGUOUS option is meaningful only when a file is created. 
2. This option applies only to disk files. | 


3. If specified with the CONTIGUOUS_BEST_TRY option, the CONTIG- 
UOUS_BEST__TRY option takes precedence. 


@ Usage 


By default, a disk file consists of areas, or extents, on a disk volume that are 
not contiguous. When a file is accessed, the file system must maintain a 
pointer to each extent. However, there is a maximum number of extents that 
can be maintained. For very large files that must be accessed quickly, an 
initial allocation of contiguous space can result in more efficient input/output 
operations. 
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@ Usage 


The time value required can be obtained by using the SYS$BINTIM (Convert 
ASCII String to Binary Time) system service procedure. For an example of a 
call to this procedure to obtain a system time value for the CREATION 
DATE option, see Section 19.4.3, “Timer and Time Conversion Routines.” 


6.2.11 CURRENT_POSITION Option 


The CURRENT_POSITION option specifies that a magnetic tape volume be 
positioned immediately after the most recently closed file when the next file is 
created. The format of this option is: 


CURRENT_POSITION [ (boolean-expression) ] 


@ Rules 
1. The CURRENT_POSITION option is meaningful only when a file is 
created. 


2. This option applies only to magnetic tape files. 


3. If the REWIND_ON_OPEN option is also selected, it takes precedence 
over the CURRENT_POSITION option. 


@ Usage 


This option lets you close an output file on a magnetic tape and proceed to 

write another file on the tape immediately after the current file. For example: 

DECLARE TAPEFILE FILE RECORD OUTPUT ENVE | 
“DEFAULT _FILE_NAME( ‘TAPEFILE:°3)3 


QPEN FILECTAPEF ILE) ENVCCURRENT.POS IT TON) 
ti Lele PAP ede r he ds 


CLOGE PELECIAPEP LLE S34 
OPEN ILE TAPEFILE?) TEILEC* TAPES. Ih? 33 


When the second OPEN statement executes, the tape identified by the logical 
name TAPEFILE remains positioned as it was following the CLOSE state- 
ment. 


Magnetic tape file positioning is described in Section 10.2, “Using Magnetic 
Tape Files.” 
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m@ Usage 


The DEFERRED_WRITE option can provide better I/O performance for 
output operations, especially when a relative or indexed sequential file is 
being initially loaded with records and the records are being added sequen- 
tially. 


If a system problem occurs when I/O is being performed with the 
DEFERRED_WRITE option enabled, data may be lost. To ensure the integ- 
rity of the file during processing with this option, a PL/I program can call the 
FLUSH built-in subroutine at critical times to rewrite all buffers. The 
FLUSH built-in subroutine is described in Chapter 8, ‘‘File-Handling Built-In 
Subroutines.” 


6.2.14 DELETE Option 


The DELETE option specifies that the file is to be deleted when it is closed. 
The format of this option is: 


DELETE [ (boolean-expression) |] 


@ Rules 
1. The DELETE option can be specified when a file is created, opened, or 
closed. 


2. Once the DELETE option has been enabled for a file on a particular open, 
it cannot be disabled. 


@ Usage 


When this option is used in conjunction with the SPOOL or BATCH options, 
the file is marked to be deleted after it is either printed or processed as a batch 
job. 

This option can also be used to delete an existing file. For example: 


DECLARE INFILE FILES 
OPEN FILE <INFILE) ENVIRONMENT(OELETE? 3 
CLOSE FLEE CINE TLE Is 


When this CLOSE statement executes, the VAX/VMS file associated with the 
PL/I file constant INFILE is deleted. 


6.2.15 EXPIRATION DATE Option 


The EXPIRATION_DATE option specifies the time at which a magnetic 
tape file expires. The file cannot be deleted or overwritten until the specified 
date. The format of the EXPIRATION_DATE option is: 


EXPIRATION_DATE (variable-reference) 
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Each time the addition of a record to a file requires the file system to allocate 
additional disk extents for the file, RMS allocates the amount of space speci- 
fied by the EXTENSION_SIZE value. Thus, if you specify a value that is 
larger than the default that RMS uses, the number of times that a file must 
be extended will be decreased. 


However, if a large extension quantity is specified for a file, and the file does 
not require the allocated space, the disk space is wasted. 


6.2.17 FILE_ID Option 


When the FILE_ID option is specified in the opening of an existing file, PL/I 
uses the value specified in the FILE_ID option to locate the file. This format 
of the option is: 


FILE_ID(variable-reference) 


variable-reference 
Specifies the name of a six-element array variable that gives the file identi- 
fication obtained when the file was created. 


The variable must be declared as (6) FIXED BINARY(31) and must be 
connected. 


@ Rules 
1. The FILE_ID option is valid only when an existing file is opened. 


2. This option conflicts with the TITLE, DEFAULT_FILE_NAME, and 
FILE_ID__TO options. 


3. If there is no file with the indicated file identification, the UNDEFINED- 
FILE condition is signaled. 


mM Usage 


This option is provided for use with the TEMPORARY option; you must 
specify the FILE_ID option to reopen a file that was created with the 
TEMPORARY option. 


6.2.18 FILE _ID_TO Option 


When a file is created, the FILE_ID__TO option requests PL/I to return the 
file identification to a user-specified variable. Its format is: 


FILE_ID_TO(variable-reference) 


variable-reference 
Specifies the name of a six-element array variable to receive the file identi- 
fication of the created file. 


The variable must be declared as (6) FIXED BINARY(381) and must be 
| connected. 
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If the specified file size is not a multiple of the cluster size of the disk, the 
allocation is rounded up to a multiple of the cluster size. 


Note that if you allocate more space for a file than it requires, the unused 
space is wasted, since it is unavailable for other uses. 


6.2.20 FIXED_CONTROL_SIZE Option 


The FIXED_CONTROL_SIZE option specifies that a file will have a fixed- 
length control area associated with each variable-length record and specifies 
the size of the fixed control area. 


The format of this option is: 
FIXED_CONTROL_SIZE(integer-expression) 


integer-expression 
Is an integer expression in the range 0 to 255, indicating the number of 
bytes in the fixed control field of the record. If you specify a value of 0, PL/I 
uses the default size of two bytes. 


@ Rules 


1. The FIXED_CONTROL_SIZE option is meaningful only when a file is 
created. 


2. This option applies only to relative and sequential files with variable- 
length records. 


3. The FIXED_CONTROL_SIZE option conflicts with the BLOCK_IO 
and INDEXED options and with the STREAM and UPDATE file de- 
scription attributes. 


4. You must specify the FIXED_CONTROL_SIZE option to create a file 
containing records with a fixed-length control area. 


| Usage 

When a file is created with the FLIXED_.CONTROL_SIZE option, WRITE 
and REWRITE statements for the file may specify the FIXED_.CONTROL_ 
FROM option to write a value into the fixed control area. For example: 


DECLARE OUTFILE FILE RECORD OUTPUT ENVIRONMENT ¢ 
PIAED. CONTROL STEER ti) 2s 


OPEN FICE C GUT ILE) 
WRITE FILE (GUTFICE) FROM «NEWLINE? OPTIONS 4 
FIXEDUCONTROL FROM(LINE NUMBER) ) 5 


If the FIXED_CONTROL_FROM option is not specified when a record is 


written to a file with fixed control records, VAX-11 PL/I writes zeros in the 
fixed control area of the record. 


The format of variable-length records with a fixed-length control area is de- 
scribed in Section 9.3.3, ‘“Variable-Length Records with a Fixed-Length Con- 
trol Area.” For an additional example of writing a file with a fixed control 
area, see Section 7.2.3, “FIXED_CONTROL__FROM Option.” 
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6.2.23 GROUP_PROTECTION Option 


The GROUP_PROTECTION option defines the type of access to be permit- 
ted to the file by other users in the owner’s group. The format of this option is: 


GROUP_PROTECTION (character-expression) 


character-expression 
Is a one- to four-character string expression indicating the access privileges 
to be granted to users in the owner’s group. The expression can contain any 
of the following letters to indicate the access allowed: 


Letter Meaning 


R Read access is allowed 
W Write access is allowed 
E Execute access is allowed 
D Delete access is allowed 


The lowercase forms of these letters are also permitted. Letters may be 

repeated, but the maximum length of the string is four. All other characters 
are invalid. If any other character is present in the string, the UNDE- 

FINEDFILE condition is signaled. 


@ Rules 
1. The GROUP_PROTECTION option is meaningful only when a file is 
created. 


2. If no protection options are specified, PL/I uses the current system and 
process defaults. If any protection options are specified, the protection for 
unspecified user categories defaults to no access. 


@ Usage 


For information on specifying protection options, see Chapter 13, “‘File Pro- 
tection and File Sharing.”’ 


6.2.24 IGNORE_LINE_ MARKS Option 


The IGNORE_LINE_MARKS option overrides the default manner in which 
VAX-11 PL/I interprets end-of-line indicators on stream input operations, 
which is to treat an end-of-line on a stream input operation as a field delimiter 
in a GET LIST or GET EDIT statement. The format of this option is: 


IGNORE_LINE_-MARKS [ (boolean-expression) ] 


@ Rules 
1. The IGNORE_LINE_MARKS option may be specified when a file is 
opened. 


2. This option applies only to stream input files; that is, it conflicts with the 
RECORD, OUTPUT, and UPDATE attributes and with any attributes 
that imply these attributes. 
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6.2.26 INDEXED Option 


The INDEXED option specifies that a file is an indexed sequential file. The 
format of this option is: 


INDEXED [ (boolean-expression) ] 


@ Rules 
1. The INDEXED option is meaningful when an existing file is opened. 
2. This option applies only to indexed sequential files. 


3. INDEXED conflicts with the APPEND, BATCH, BLOCK_IO, FIXED_ 
CONTROL_SIZE, MAXIMUM_RECORD_NUMBER, and 
PRINTER_FORMAT options and with the PRINT file description 
attribute. 


@ Usage 


The INDEXED option is never required; however, you may use it as a check 
when you open an existing indexed sequential file so that PL/I will verify the 
file’s organization before opening it. 


6.2.27 INITIAL_FILL Option 


The INITIAL_FILL option specifies, when an indexed sequential file is 
opened, that the initial fill value specified when the file was created is to be 
used. The format of this option is: 


INITIAL_FILL [ (boolean-expression) ] 


@ Rules 


The INITIAL_FILL option is meaningful only when an indexed sequential 
file is initially opened for output. 


m@ Usage 


As an indexed sequential file is initially loaded with records, the fill size 
specified causes buckets to appear full when they are actually less than full. 
Thus, room remains in each bucket for subsequent additions to the file. 


For information on using indexed sequential files, see Chapter 12, “Indexed 
Sequential Files.”’ 


6.2.28 MAXIMUM_RECORD_NUMBER Option 


The MAXIMUM__RECORD__NUMBER option sets, for a relative file, the 
largest record number that can be written to the file. 


The format of this option is: 
MAXIMUM_RECORD_NUMBER(integer-expression) 
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integer-expression 
Is a numeric expression with values in the range of 1 to a maximum deter- 
mined by record format and file organization, as follows: 


Maximum 
File Organization Record Format Allowed 
Sequential Fixed or variable length 32,767 
Relative Fixed length 16,383 
Relative Variable length 16,381 
Indexed sequential Fixed length 16,362 
Indexed sequential Variable length 16,360 


For variable-length records with a fixed-length control area, the size of the 
fixed control area must be subtracted from the maximum value allowed. 


A value of 0 indicates that there is no user-defined limit to the size of 
records. 


If the value is out of range, the UNDEFINEDFILE condition is signaled. 


@ Rules 


The MAXIMUM_RECORD_SIZE option is meaningful only when a file is 
created. If not specified, PL/I provides a default length based on the file 
organization and record format, as follows: 


File Organization Record Format Default 
Sequential Fixed length | p12 
Sequential Variable length — 510 
Relative Fixed or variable length 480 


If the file has variable with fixed-length control records, the size of the fixed 
control area is subtracted from the default value listed above. 


6.2.30 MULTIBLOCK_COUNT Option 


The MULTIBLOCK_COUNT option specifies the number of blocks to allo- 
cate in each internal buffer for operations on a sequential disk file. Its format 
is: 


MULTIBLOCK__COUNT(integer-expression) 


integer-expression 
Is a fixed binary expression in the range of 0 to 127, indicating the number 
of blocks to be allocated to each buffer. If 0 is specified, PL/I uses the 
system default. You can determine the current system default by entering 
the DCL command SHOW RMS_DEFAULT. Use the SET RMS _ 
DEFAULT command to establish a new default value, if desired. 


If the value is not within the required range, the UNDEFINEDFILE condi- 
tion is signaled. 
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@ Rules 


1. The MULTIBUFFER_COUNT option is meaningful when a file is 
created or opened. 


2. This option applies only to disk files. 
3. This option has no effect if BLOCK_IO is specified. 


m@ Usage 


When you use the MULTIBUFFER_COUNT option, it decreases the number 
of actual data transfers and thus increases a program’s execution speed. For 
example: 
OPEN FILE(REL_FILE) 
ENY 1 RONMENT ( 

READ_AHEAD + 

MULTIBLOCK_COUNT(4) > 

MULTIBUFFER COUNT(4))3 
This option can be specified for sequential, relative, or indexed sequential 
files. For inserting records in an indexed sequential file, a good rule of thumb 
is to specify one buffer for each index in use, plus two or more buffers for data. 
Thus, an indexed sequential file with a primary key and two alternate keys 
could be opened with: 


ENVIRONMENT (MUL TIBUFFER COUNT(S)) 
This option specifies five buffers. 


Multibuffering is also effective for sequential files when combined with the 
ENVIRONMENT options READ_AHEAD or WRITE_BEHIND. These 
options are described individually in this chapter. 


6.2.32 NO _SHARE Option 


The NO__SHARE option prohibits sharing of the data in a file. The format of 
the NO_SHARE option is: 


NO__SHARE [ (boolean-expression) ] 
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M@ Usage 


Note that although the value may be specified to PL/I in decimal, the 
VAX/VMS system always displays UICs in octal format. For information 
on specifying protection options, see Chapter 13, “File Protection and File 
Sharing.” 


6.2.34 OWNER _MEMBER Option 


The OWNER_MEMBER option overrides the default member number in the 
user identification code associated with the file’s owner. The member number 
of a file’s owner, together with the group number, provides Bbonecuon for the 
file. Its format is: 


OWNER_MEMBER(integer-expression) 


integer-expression 
Is a numeric value in the range of 0 to 255. 


@ Rules 


1. The OWNER_MEMBER option is meaningful only when a file is cre- 
ated. 


2. If not specified, PL/I uses the member number in the current UIC. 


3. To specify an owner UIC for a file that is different than the UIC under 
which the current program is executing, the process must have the 
SYSPRV user privilege or must have a system UIC. 


@ Usage 


Note that although the value may be specified to PL/I in decimal, the 
VAX/VMS system always displays UICs in octal format. For information 
-on specifying protection options, see Chapter 13, “File Protection and File 
Sharing.” - 
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@ Rules 


1. The PRINTER_FORMAT option is meaningful only when a file is cre- 
ated. 


2. The FIXED_CONTROL_SIZE option should be specified with the 
PRINTER_FORMAT option. The size of the fixed control area must be 
two to six bytes. If FIXED_CONTROL_SIZE is not specified, the size of 
the fixed control area defaults to two bytes. 


3. This option may be applied only to relative or sequential files 


4, PRINTER_FORMAT conflicts with the STREAM file description attrib- 
ute and with the following ENVIRONMENT options: 


CARRIAGE_RETURN_FORMAT 
FIXED_LENGTH_RECORDS 
BLOCK_IO 


mM Usage 


This option indicates that a file is in printer format, that is, that the fixed 
control area of each record contains carriage control information. Printer file 
format provides more explicit carriage control than the default type of car- 
riage control, called carriage return format. Printer format is particularly 
useful in formatting a printed listing. 


Table 6-2 summarizes the coding specifications for the fixed-length control 
area for files with printer format. The first byte in the fixed control area is 
called the prefix byte: it gives the carriage control to perform before writing 
the record. The second byte is the postfix byte: it gives the carriage control to 
perform after writing the record. The values shown in Table 6-2 have the 
same meanings in either byte; the bytes are interpreted separately. 


Table 6-2: Printer File Format Carriage Control 


No carriage control 


Bits 0 through 6 contain the count of line 
feeds 


Bit 7 | Bit 6 Bit 5 Meaning 


i} 0 0 The carriage control is specified by the ASCII 
value in bits 0 through 4. 





The carriage controls associated with the ASCII values are listed in the table 
of ASCII codes in Appendix D. 
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Sample Program 6-1: Explicit Carriage Control 


PRINTER_FORMAT_EXAMPLE: PROCEDURE OPTIONS(MAIN) 3/1 


7/* Declare structure definitions for carriage control bit fields */ 
/* and a FIXED BIN(15) variable for the fixed control area */ 1) 


DECLARE 1 LINE_FEEDS STATIC» 
2 COUNT BIT(7)>+ 7/* contains count of line feeds */ 
2 INDICATOR BIT(1) INIT(‘O’B) +/* must be zero */ 
1 CARRIAGE_CONTROL STATIC, 


2 CODE BIT(S)+s /* bits O-4 ASCII code for action */ 
2 FILLER BIT(2) INIT(’OO’b) +s /* bits S and G */ 
2 EXPLICIT BIT(i) INIT(’1’B),» /* bit 7 must be set ¥*/ 


CONTROLUFIELD BIT(1G) ALIGNED; 
/*® Set up variables for Form Feeds and CRs ¥*/ 


DECLARE (NEWLINE +»NEW_PAGE) BIT(8), 2) 
I FIXED: 


I= 1235 7*® ASCII decimal code for Form Feed */ 
CODE = UNSPEC(I) 5 /* assign 12 to CODE field ¥*/ 
NEW PAGE = STRING(CARRIAGE CONTROL) 5 


I = 133 /* ASCII decimal code for CR */ 
CODE = UNSPEC(I) 5 /* assign 13 to CODE field +*/ 
NEWULINE = STRING(CARRIAGE_CONTROL) 5 


/* declare and open PRINTFILE>s with character-string variable for I/O #/ 
DECLARE PRINTFILE RECORD OUTPUT FILE ENY( 
FIXED_CONTROL_SIZE(2) + 
PRINTER FORMAT) + 
PRINTREC CHARACTER(80) VARYINGS 


OPEN FILE¢PRINTFILE) 3 

/*® output first line with no carriage control ¥*/ 
PRINTREC = ‘Output first line with mo carriage control’s 4.) 
WRITE FILE(PRINTFILE) FROM(PRINTREC) 3 

/* Prepare to output five line feeds followed by a new line */ 
I = 35 /* assign 5 to LINE__FEEDS.COUNT */ 
LINE_FEEDS,COUNT = UNSPEC(I); 
CONTROL_FIELD = STRING(LINE_FEEDS);::NEW LINE: 
PRINTREC = ‘Record preceded ty 5S line feeds 75 


WRITE FILE(PRINTFILE) FROM (PRINTREC) OPTIONS ( 
FIXEDUCONTROL_FROM(CONTROL_FIELD))3 


f*® Prepare to output a Page eject followed by a new line */ 


CONTROLUFIELD = NEW. PAGE: }NEW_LINES © 
PRINTREC = ‘New Page’; 


WRITE FILE(PRINTFILE) FROM(PRINTREC) OPTIONS ( 7) 
FIXED_CONTROL_FROM(CONTROL_FIELD)) 3 


CLOSE FILE(PRINTFILE) ENV(SPOOL) 5 3) 
END 3 
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6.2.39 RECORD_ID_ACCESS Option 


The RECORD_ID.__ACCESS option indicates that the records in a file will 
be accessed randomly using the internal identification of’ the records. The 
format of this option is: 


RECORD_ID__ACCESS [ (boolean-expression) ] 


@ Rules 
1. The RECORD_ID_ACCESS option is meaningful when a file is created 
or opened. 


2. This option applies only to disk files. 


3. The RECORD_ID_ACCESS option conflicts with the BLOCK_IO op- 
tion. 


@ Usage 


You must open a file with this option to use the RECORD_ID_TO and 
RECORD__ID options of the record I/O statements. These options are de- 
scribed in Chapter 7, “I/O Statement Options.”’ 


When a file is opened with the RECORD_ID__ACCESS option, access by 
record identification can be mixed with sequential access or access by key 
during this open of the file. However, a statement cannot specify a record both 
by key and by record identification. 


6.2.40 RETRIEVAL_POINTERS Option 


The RETRIEVAL_POINTERS option specifies the number of extent 
pointers to be maintained in main memory for file access. Each pointer pro- 
vides access to a separate extent in the file; increasing the number of pointers 
for a noncontiguous file can increase the speed with which records are ac- 
cessed during I/O operations. Its format is: 


RETRIEVAL__POINTERS (integer-expression) 


integer-expression 
Is a fixed binary expression in the range of 0 to 127, or -1. A value in the 
range of 1 to 127 indicates the number of pointers. If you specify -1, the file 
system maps as much of the file as possible. If the option is not specified, or 
if the expression has a value of 0, the file system uses the default number 
established when the volume was initialized or mounted. 


@ Rules 


The RETRIEVAL_POINTERS option is meaningful when a file is created or 
opened. 


Options of the ENVIRONMENT Attribute 6-39 


M@ Usage 


Magnetic tape file positioning is described in Section 10.2, ““Using Magnetic 
Tape Files.”’ 


6.2.43 SCALARVARYING Option 


The SCALARVARYING option specifies that character strings with the 
VARYING attribute will be read and written in strict accordance with the 
PL/I ANSI standard. Its format is: 


SCALARVARYING |[ (boolean-expression) ] 


m@ Rules 

1. The SCALARVARYING option is meaningful when a file is created or 
opened. 

2. SCALARVARYING conflicts with the STREAM file description attrib- 
ute. 

@ Usage 


The SCALARVARYING option has the following effect on input/output oper- 
ations involving VARYING character-string variables: 


e When a record is written from a varying-length character string, the entire 
storage of the string is written, including the word containing the string’s 
current length. 


° When a record is read into a varying-length character-string variable, the 
first word of the record is read into the variable’s current length field. 


Thus, records to be read into or from variables with the VARYING attribute 
should be images of a varying character string — including the two-byte count 
field at the beginning of the string. 


When SCALARVARYING is not specified, character-string variables with the 
VARYING attribute are handled so as to facilitate reading and writing files 
with variable-length records. The rules are: 


e On an input operation, the entire record read into the variable is treated as 
a character string and assigned to the variable. Thus, the current length of 
the variable is always set to the record length of the record read, unless 
truncation occurs. 


¢ On an output operation, only the characters of the string’s current value are 
written. 


For strings with the VARYING attribute that are embedded in arrays or 
structures, the entire storage is always read or written. 


- When a file is to be read with SCALARVARYING in effect, the target varia- 
ble must be declared CHARACTER VARYING and the length of the target 
variable must match the record length of each record in the file, minus two 
bytes. If the length does not match, the ERROR condition is signaled. 
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@ Rules 


1. The SHARED_WRITE option is meaningful when a file is created or 
opened. 


2. This option applies to relative and indexed sequential files. 
3. SHARED_WRITE conflicts with the NO_SHARE option. 


4, If SHARED_-READ and SHARED_WRITE are both specified, the effect 
is the same as if only SHARED_WRITE were specified. 


@ Usage 
By default, the SHARED_WRITE option is disabled. 


For information on file sharing, see Chapter 13, ‘File Protection and File 
Sharing.” 


6.2.46 SPOOL Option 


The SPOOL option requests that the file be submitted to the system printer 
job queue when it is closed. The format of this option is: 


SPOOL |[ (boolean-expression) ] 


@ Rules 
1. The SPOOL option can be specified when a file is created, opened, or 
closed. 


2. This option applies to stream files as well as to record files of any file 
organization. 


3. Once the SPOOL option has been specified for a file on a particular open, 
it cannot be disabled. 


mM Usage 


If you specify the DELETE option in conjunction with the SPOOL option, the 
file is submitted to the queue SYS$PRINT when it is closed and marked to be 
deleted after printing. 


You can control the queue to which the file is submitted by using the DEFINE 
command to equate the logical name SYS$PRINT with the name of a specific 
queue before running the program. For example: 


$ DEFINE SYS#PRINT LPCO: 
$ RUN PRINTER 


If the PL/I program PRINTER closes a file with the SPOOL option, the file is 
queued to the printer device LPC0:. 
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The lowercase forms of these letters are also permitted. Letters may be 
repeated, but the maximum length of the string is four. All other characters 
are invalid. If any other character is present in the string, the UNDE- 
FINEDFILE condition is signaled. 


@ Rules 
1. The SYSTEM_PROTECTION option is meaningful only when a file is 


created. 


2. If no protection options are specified, PL/I applies the current system and 
process defaults. If any protection options are specified, the protection for 
unspecified user categories defaults to no access. 


@ Usage 


For information on specifying protection options, see Chapter 13, ‘“‘File Pro- 
tection and File Sharing.” 


6.2.49 TEMPORARY Option 


The TEMPORARY option creates a temporary file with no directory entry. 
The format of this option is: 


TEMPORARY |[ (boolean-expression) ] — 


@ Rules 
1. The TEMPORARY option is meaningful only when a file is created. 


2. TEMPORARY conflicts with the TITLE and the DEFAULT_FILE_ 
NAME options. 


m@ Usage 


When you create a file with the TEMPORARY option, the file system does 
not create a directory entry for the file. A file thus created can be used during 
the execution of the program and deleted on completion, without the overhead 
required to create and remove the directory entry. 


The file may be deleted when it is closed or, if needed later, deleted after it 
has been reused. 
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M@ Usage 


You can specify this option to conserve disk space. If a file’s allocation is 
greater than is required for the contents of the file, and if the file is not 
expected to increase in size, you may want to use this option to reclaim the 
allocated but unused space. 


6.2.51 WORLD_PROTECTION Option 


The WORLD__PROTECTION option defines the type of access to be permit- 
ted to the file by users who are not in the owner’s group and who do not have 
system user identification codes. The format of this option is: 


WORLD_PROTECTION(character-expression) 


character-expression 
Is a one- to four-character string expression indicating the access privileges 
to be granted to users in the world category. The character-string expres- 
sion can contain any of the following letters to indicate the access allowed: 


Letter Meaning 

R Read access is allowed 
W Write access is allowed 
E Execute access is allowed 
D Delete access is allowed 


The lowercase forms of these letters are also permitted. Letters may be 
repeated, but the maximum length of the string is four. All other characters 
are invalid. If any other character is present in the string, the UNDE- 
FINEDFILE condition is signaled. 


@ Rules 
1. The WORLD__PROTECTION option is meaningful only when a file is 
created. . 


2. If no protection options are specified, PL/I uses the current system and 
process defaults. If any protection options are specified, the protection for 
unspecified user categories defaults to no access. 


m@ Usage 


For information on specifying protection options, see Chapter 13, “File Pro- 
tection and File Sharing.” 


6.2.52 WRITE_BEHIND Option 


The WRITE_BEHIND option requests the file system to overlap the writing 
of buffers with computing operations. The format of this option is: 


WRITE_BEHIND [ (boolean-expression) ] 
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Chapter 7 
1/O Statement Options 


VAX-11 PL/I permits the specification of the OPTIONS keyword on I/O 

_ statements and supports certain options for each statement. This chapter 
describes how to code options for I/O statements, lists the valid options for 
each I/O statement, and describes each option individually. 


7.1 How to Code I/O Statement Options 


All options are specified in an option list following the OPTIONS keyword, as 
follows: 


OPTIONS (option,...) ; 
Options must be separated by commas and enclosed in parentheses. For 
example: 


GET LIST (PASSWORD) OPTIONS ¢ 
PROMPT( ‘Enter password: ‘)-s 
NOLECHO: 
PURGE_TYPE_ AHEAD? 3 


_ Any option that does not require an argument may be followed by a Boolean 
expression in the format: 


option(boolean-expression) 


If no Boolean expression is specified and the option is present in the option 
list, the default value of true is supplied. 


7.2 Summary of I/O Statement Options 


Table 7-1 lists the I/O options and indicates which options are valid for each 
1/O statement. 


7.2.1 CANCEL CONTROL_O Option 


The CANCEL_CONTROL_O option specifies, when the output device is a 
terminal, that the effect of is disabled prior to output. This ensures that 
the beginning of the output list is displayed. 


@ Rules 
1. The CANCEL_CONTROL_ 0 option is valid only on a PUT statement. 


2. This option is ignored when the output device is any device other than an 
interactive terminal. 


mm Usage 


Use this option on a PUT statement that you want to display regardless of 
whether previous output has been interrupted by (tai). By default, the 
function remains in effect until another ¢TRi/o). For example: 


PUT SKIP LIST(’Phase 1 complete... beginning Phase Fi... 73 
OPTIONS (CANCELUCONTROL_O} 3 


If program output had been suspended by before this PUT statement 
executes, the PUT statement cancels the effect of the CiRLio) and outputs the 
data list. 


7.2.2 FAST_DELETE Option 


The FAST__DELETE option specifies, for a record in an indexed sequential 
file with alternate indexes, that only the current index for the file is to be 
updated. 


The alternate indexes for the deleted record are not updated until the next 
time access is attempted to the record through the alternate index. 


@ Rules 
1. The FAST_DELETE option is valid only on a DELETE statement. 


2. This option applies only to indexed sequential files. 


M@ Usage 


This option can improve the speed of deletions when an indexed sequential 
file is updated. 


7.2.3 FIXED_CONTROL_FROM Option 


The FIXED_CONTROL_FROM option specifies a value to be written in the 
fixed control portion of a record in a file with variable-length records and a 
fixed control area. The format of the option is: 


FIXED_CONTROL_FROM (variable-reference) 
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7.2.4 FIXED_CONTROL_TO Option 


The FIXED_CONTROL_TO option specifies that the contents of the fixed 
control area of a record in a file with a fixed control area are to be assigned to 
a specified variable. The format of the option is: 


FIXED_CONTROL_TO (variable-reference) 


variable-reference 
Specifies the variable associated with the fixed control area. The variable 
can be a scalar or a connected aggregate variable. It must not be an 
unaligned bit string or an aggregate consisting entirely of unaligned 
bit-string variables. 


@ Rules 
1. The FIXED_CONTROL_TO option is valid only on a READ statement. 


2. The file must have variable-length records with a fixed-length control area 
and must be opened with the INPUT attribute and with the 
ENVIRONMENT option FIXED_CONTROL_SIZE_TO. 


3. If the file is an existing file, the length of the variable must match the 
length of the fixed control area. If the length is not correct, the ERROR 
condition is signaled. 


7.2.5 INDEX_NUMBER Option 


The INDEX_NUMBER option specifies the particular index in an indexed 
sequential file to which a KEY option applies (primary index, secondary 
index, and so on). 


The format of this option is: 
INDEX_NUMBER (integer-expression) 


integer-expression 
Specifies the index to use. The value of expression must be the number of 
an index for records in an indexed sequential file. The primary index is | 
zero, the secondary index is one, and so on. 


@ Rules 


1. The INDEX_NUMBER option is valid on a READ, REWRITE, or 
DELETE statement. 


2. The file must be an indexed sequential file, and the KEY option must also 
be specified on the statement. 
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In the following example, STATE _FILE’s third alternate key (that is, index 
number three) is a fixed binary population value: 


DECLARE 1 STATE: 


2 NAME CHARACTER( 20),  f*# Primary key #/ 
2 POPULATION FIXED BINARY(3135/#* index #3%/ 
? CAPITAL: 


+ 


SIZE FIXED BINARY (31) + 
STATE_-FILE FILE RECORD INPUT KEYED SEQUENTIAL? 


e 


GET SKIP LIST(SIZE) OPTIONS ( PROMPT 
‘Population values: %))4 

READ FILECSTATE_LFILE) INTOC(CSTATE) KEY(SIZE) 
OPTIONS (MATCH UGREATER+INDEXUNUMBER(3)3)5 


This READ statement obtains the record for the state whose population is 
greater than the value entered for the GET statement. For example, a value 
may be entered in response to this prompt as follows: 


Population value: 8000000 


In this case, the READ statement would read the first record in the index 
numbered three whose key value is greater than 8000000. 


7.2.7 MATCH_GREATER_EQUAL Option 


The MATCH_GREATER__EQUAL option specifies that the record of inter- 
est is the record whose key matches the key specified in the KEY option or, if 
no match is found, the first record whose key is greater than the key specified. 


@ Rules 


1. The MATCH_GREATER_EQUAL option is valid on the READ, 
REWRITE, and DELETE statements. 


2. The KEY option must also be specified. 
The file must be an indexed sequential file or a relative file. 


4, MATCH _GREATER_EQUAL conflicts with the MATCH_GREATER 
option. | 


When MATCH_GREATER_EQUAL has been specified, it remains in effect 
for all subsequent keyed accesses of the file, until overridden by its specifica- 
tion with a false Boolean value or by the MATCH_GREATER option. 
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7.2.10 PROMPT Option 


The PROMPT option specifies, when the input device is a terminal, a charac- 
ter-string prompt to be displayed prior to actual input. The format of this — 
option is: 


PROMPT (string-expression) 


string-expression 
Specifies a 1- to 254-character string expression. 


@ Rules 
1. The PROMPT option is valid only on a GET statement. 


2. This option is meaningful only when the input device is a terminal. 


M@ Usage 


Unlike a PUT statement followed by a GET statement, a GET statement 
with the PROMPT option is actually executed as a single statement. For 
example: | 


GET LIST (NUM) OPTIONS ¢(PROMPT( ‘Enter numbers $395 


When this statement is executed, the terminal display would be as follows: 


Enter numbers d4 (et 
The prompting string and the input data occur in the same statement. 
On a terminal, use of the PROMPT option provides the following benefits: 


1. If the display of the prompting string is interrupted, for example, by a 
broadcast message, the entire string is redisplayed following the message 
that interrupted it. 


2. If or is entered in response to the prompt, the prompt message 
is repeated until data is entered. 


The PROMPT option causes any data that was not processed by the last GET 
operation to be ignored. If the SKIP option is not specified, the prompt is 
output at the current cursor position. If the SKIP option is specified in con- 
junction with the PROMPT option, the SKIP operation is performed before 
the prompting message is displayed. 
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mM Usage 


The following example illustrates a record whose record identification is saved 
for a later access of the file: 
DECLARE BOOKFILE FILE RECORD KEYED: 

INBUF CHARACTER(180) VARYING: 

SAVE_RECORD_ID(2) FIXED BINARY(31)>, 

KEYVALUE CHARACTER(10) 3 


+ 


OPEN FILE(BOOKFILE) ENV(RECORD_ID_ACCESS) 5 
READ FILE(BOOKFILE) INTOCINBUF) KEY(KEYVALUE) 
OPTIONS(RECORDLID_TO(SAVE_RECORD_ID))3 


CLOSE FILE(BOOKFILE?) $ 


+ 


OPEN FILE(BOOKFILE) INPUT ENV CRECORDLID_ACCESS) 3 
READ FILECBOOKFILE) INTOCINBUF) OPTIONS ( 
RECORD. TID UFROM(SAVE_RECORD_ID)) 3 


During the first open of the file, the record identification of a specified record 
is obtained and saved. When the file is subsequently reopened, this value is 
used to access a record and to effectively position the file at that record. 


7.2.13 RECORD_ID_TO Option 


The RECORD_ID_ TO option specifies the name of a variable to be assigned 
the value of the record identification of the record on which the current opera- 
tion is being performed. 


The format of this option is: 
RECORD_ID_ TO (variable-reference) 


variable-reference 
Is a reference to a two-element array variable to receive the value of the 
record’s identification. 


The variable must be declared as (2) FIXED BINARY(81) and it must be 
connected. 


@ Rules 


1. The RECORD_ID_TO option is valid on the READ, WRITE, and 
REWRITE statements. 


2. The file on which the operation is being performed must have been opened 
with the RECORD__ID_ ACCESS option of the ENVIRONMENT attrib- 
ute. 
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Chapter 8 
File-Handling Built-In Subroutines 


In addition to the PL/I input and output statements and the functions and 
features available through the options of the ENVIRONMENT attribute, 
there are also several built-in file-handling subroutines. These subroutines 
invoke VAX-11 RMS procedures. They are called built-in subroutines be- 
cause you do not need to declare them before using them in a PL/I program. 
These subroutines are summarized in Table 8-1. They are described individu- 
ally beginning in Section 8.1. 


Table 8-1: Summary of File-Handling Built-In Subroutines 


Subroutine Function 


DISPLAY Returns information about a file. 
EXTEND Allocates additional disk blocks for a file. 


FLUSH Requests the file system to write all buffers onto disk to preserve the 
current status of a file. 


NXTVOL Begins processing the next volume in a multivolume tape set. 


REWIND Positions a file at its beginning or at a specific record. 
SPACEBLOCK | Positions a file forward or backward a specified number of blocks. 





8.1 DISPLAY Built-In Subroutine 


The DISPLAY built-in subroutine returns information about a specified file. 
Its calling sequence is: 


CALL DISPLAY (file-reference,variable-reference) ; 


file-reference 
Specifies the file variable or constant for which information is to be ob- 
tained. If the file is not currently open, the DISPLAY subroutine implicitly 
opens the file with the attributes specified in the declaration of the file. 


variable-reference 
Specifies the name of a structure variable into which information about the 
file is to be placed. 


@ ENVIRONMENT Option Values Returned by DISPLAY 


Table 8-2 summarizes the values returned by DISPLAY that correspond to 
ENVIRONMENT options and the data type of each structure member. For 
information on any of these ENVIRONMENT options, see the description of 
the option in Chapter 6, “ENVIRONMENT Options.” | 


Table 8-2: ENVIRONMENT Option Values Returned by DISPLAY 


| Data Type of 
Member Name Value Returned Meaning 


APPEND 

BATCH 
BLOCK__BOUNDARY__FORMAT 
BLOCK__IO 

BLOCK__SIZE 

BUCKET_SIZE 
CARRIAGE__RETURN__FORMAT 


CONTIGUOUS 


CONTIGUOUS__BEST__TRY 


CREATION__DATE 
CURRENT__POSITION 


DEFERRED__WRITE 


DELETE 
EXPIRATION__DATE 


EXTENSION__SIZE 

FILE_ID 

FILE_SIZE 
FIXED_-CONTROL_SIZE 
FIXED_-_LENGTH__RECORDS 
GROUP__PROTECTION 
IGNORE__LINE__MARKS 


INDEX__NUMBER 
INDEXED 
INITIAL_FILL 


BIT(1) 
BIT(1) 
BIT(1) 
BIT(1) 


FIXED BIN(31) 


FIXED BIN(31) 
BIT 


BIT(1) 


BIT(1) 


BIT(64) 
BIT(1) 


BIT(1) 


BIT(1) 
BIT(64) 


FIXED BIN(31) 
(6)FIXED BIN(31) 
FIXED BIN(31) 
FIXED BIN(31) 
BIT(1) 

CHAR(4) VARYING 
BIT(1) 


FIXED BIN(31) 
BIT(1) 
BIT(1) 


APPEND option is enabled/disabled 
BATCH option is enabled/disabled 
Records can cross block boundaries 
File is opened for block I/O 

Block size of file (disk files only) 
Bucket size of file (disk files only) 


Records have carriage return carriage 
control 


CONTIGUOUS option is enabled/disa- 
bled 


CONTIGUOUS__BEST__TRY option is 
enabled/disabled 


Creation date of file 


CURRENT_ POSITION 
enabled/disabled 


DEFERRED__WRITE 
enabled/disabled 


DELETE option is enabled/disabled 


option is 


option is 


Expiration date (magnetic tape files 
only) 


Current extension size (disk files only) 
File identification (disk files only) 
File allocation (disk files only) 

Size of fixed control area 

File has fixed-length records 
Protection for group members 


IGNORE__LINE__MARKS 
enabled/disabled 


option is 


Current index number 
File is an indexed sequential file 


INITIAL__FILL option is enabled/disa- 
bled 





(continued on next page) 
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@ File Attribute Information Returned by DISPLAY 


Table 8-3 summarizes the file attribute information returned by DISPLAY, 
including: : 


e PL/I file description attributes and options specified for the file 


e The file’s organization, expanded file specification, and, if the file is an 
indexed sequential file, the number of keys it has © 


All names in Table 8-3 are second-level members of the structure PLL_ 


FILE_DISPLAY. 
Table 8-3: File Attribute Information Returned by DISPLAY 


Data Type of 
Member Name Value Returned Meaning 


COLUMN__NUMBER FIXED BIN(31) Current column (stream out- 
put files only) 


| DIRECT BIT(1) File has/does not have DI- 
RECT attribute 


EXPANDED__TITLE CHAR(128) VARYING Expanded file specification 
FILE_ORGANIZATION CHAR(3) SEQ, REL, or IDX 


FORTRAN__FORMAT BIT(1) File has/does not have FTN 
(ASA) carriage control 


INPUT BIT(1) File has/does not have IN- 
PUT attribute 


KEYED BIT(1) File has/does not have 
KEYED attribute 


LINE__NUMBER FIXED BIN(31) Current line number (stream 
output files only) 


LINESIZE FIXED BIN(31) File’s line size (stream output 
files only) 


NUMBER__OF__KEYS FIXED BIN(31) Number of keys (indexed se- 
quential files only) 


OUTPUT BIT(1) File has/does not have OUT- 
PUT attribute . 


PAGE__NUMBER FIXED BIN(31) Current page number 
(PRINT files only) 


PAGESIZE FIXED BIN(31) Page size (PRINT files only) 


PRINT ‘BIT(1) File has/does not have 
PRINT attribute 


RECORD BIT(1) File has/does not have REC- 
ORD attribute 


SEQUENTIAL BIT(1) File has/does not have SE- 
QUENTIAL attribute 


STREAM BIT(1) File has/does not have 
STREAM attribute 


UPDATE | BIT(1) File has/does not have UP- 
DATE attribute 
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Table 8-4 (Cont.): Device Information Returned by DISPLAY 


Member . 
Name Meaning 


Device is/is not spooled © 


Device is/is not sequential block-oriented (magnetic tape) 


Device is/is not currently software write-locked 


Device is/is not a terminal 


Device performs write checking 





8.2 EXTEND Built-In Subroutine 


The EXTEND built-in subroutine increases the amount of space allocated to 
a disk file. Its calling sequence is: 


CALL EXTEND (file-reference,integer-expression) ; 


file-reference 
Specifies the name of a file variable or constant associated with the file that 
is to be extended. If the file is not currently opened, the EXTEND subrou- 
tine opens the file with the OUTPUT attribute in order to extend it. 


integer-expression . 
Is a fixed binary expression in the range of 0 to 4,294,967,295, specifying the 
number of 512-byte disk blocks to add to the file. If 0 is specified, PL/I uses 
the default extension quantity for the file. 


To specify a value larger than 2,147,483,647 (the largest value that can be 
contained in a fixed binary integer in PL/I), you must express the number 
as a negative value; RMS inteprets the number as an unsigned integer. 


@ Usage 


Use the EXTEND built-in subroutine to explicitly extend a file during pro- 
cessing. Normally, RMS extends a file automatically, using a current exten- 
sion size value, whenever an output operation causes a file to exceed its 
allocated space. The default value that RMS uses to extend a file is set by the 
ENVIRONMENT option EXTENSION_SIZE. 


You can improve the performance of a program that is going to add a large 
number of records to a file by an explicit call to EXTEND before adding 
records to the file. If the call to EXTEND occurs before records are added, 
then RMS does not need to extend the file during the actual I/O operations. 
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8.5 REWIND Built-In Subroutine 


The REWIND built-in subroutine positions a file so that the next record to be 
read will be the first record in the file or index. Its calling sequence is: 


CALL REWIND (file-reference) ; 


file-reference 
Specifies the name of the file constant or file variable associated with the 
file to be rewound. If the file is not currently open, the REWIND subroutine 
implicitly opens the file with the attributes specified in the declaration of 
the file. 


m@ Usage 


Use this subroutine to begin processing a file at its logical beginning. This 
subroutine is valid for disk files of all organizations and for sequential files on 
tape volumes. The position of the file following the call to the REWIND 
subroutine is as follows: | 


e If the file is a sequential file, the REWIND service positions the file to the 
first record in the file. 


e If the file is a relative file, the REWIND service positions the file to the first 
occupied cell. 


e If the file is an indexed sequential file, the REWIND service positions the 
file at the lowest key value in the current index. 


e If the magnetic tape file is on a single volume, the volume is rewound. If the 
tape file exists on a multivolume tape set, the REWIND built-in subroutine 
rewinds the file to the beginning of the volume set. 


You can also use the REWIND built-in subroutine to reposition a stream file 
after an end-of-file condition. Normally, if end-of-file (€TRUZ) on a terminal) is 
entered during an input operation on a stream input file, the PL/I program 
must close the input file and reopen it before it can read any more data. 
However, an ENDFILE ON-unit can be coded as follows: 


ON ENDFILE(STREAMFIL) CALL REWIND(STREAMFIL); 


This ON-unit calls the REWIND built-in subroutine each time an end-of-file 
is encountered for the file constant STREAMFIL. The REWIND built-in 
subroutine “repositions” the stream file at its beginning so that the program 
can continue reading input. 
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Chapter 9 
File and Record Concepts 


This chapter describes the following considerations for designing, creating, 
and using files: 


e The file organization, that is, the physical arrangment of the records in the 
file 


e The type of access that will be used to read, write, or update the records in 
the file, that is, whether the records will be accessed in sequential order or 
by a key 


e The type of record in the file, that is, whether the records are variable length 
or fixed length 


e The type of carriage control information, if any, used to print the records 
e The format of stream files 


Chapters 10 through 12 contain examples of creating and accessing files with 
different organizations and record formats in PL/I. For more detailed informa- 
tion on file design, see the RMS-11 User’s Guide. 


9.1 File Organizations 
VAX-11 RMS supports three file organizations for record files. These are: 
e Sequential 
e Relative 
e Indexed sequential 


The relative and indexed sequential file organizations are valid only for disk 
devices. To read or write files on tape or unit record devices, you must use 
sequential organization. 


The type of organization you select for a file and the attributes of the file, that 
is, the record format and size, the file size, and so on, are set when you create 
a file and need not be specified thereafter. When a program subsequently 
accesses an existing file, the file’s organization and attributes are known to 
the file system. 


9.2.1 Sequential Access 


You can access records in a file with any file organization using sequential 
access. When you access a file sequentially, each read or write operation reads 
or writes the “next” record in the file. 


As you process a file sequentially, PL/I always keeps track of the current 
record, that is, the record just read or written, and the next record, the record 
that follows the record just read or written. 


When you access a relative file sequentially, the records are read or written in 
order by relative record number. In a file in which not all cells contain records, 
sequential input operations only involve cells that contain data records. 


When you access an indexed sequential file sequentially, you may specify the 
number of the index on which to base the sequence. The “next”’ record in the 
input operation is the next ordered record in the specified index. 


9.2.2 Random Access 


When you access a file randomly by key, each input/output request must 
contain the KEY or KEYFROM option. The contents of the specified key 
depends on the file’s organization, as follows: 


e For a relative file, the key is the relative record number of the record to be 
accessed. 


e For an indexed sequential file, the key is the portion of the record defined as 
a key field. 


e In a disk file with fixed-length records, the key value is the relative record 
number of the record with respect to the beginning of the file. The first 
record in the file is relative record number 1, the second record is relative 
record number 2, and so on. 


By default, a READ statement accesses a record based on an exact match of 
the key specified. In VAX-11 PL/I, you can optionally request that the READ 
statement match any record with an equal or greater key value, or any record 
with a greater key value. 


9.2.3 Random and Sequential Access 


When you access a file for random and sequential access, you can read records 
sequentially or randomly. For example, you can use a keyed READ statement 
to position the file at a specified record and then read or process records 
sequentially from that position. 
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-9.3 Record Formats 


VAX-11 RMS allows the following types of record format: 
e Fixed-length records 

e Variable-length records 

e Variable with fixed-length control records 


Fixed-length records and variable-length records are allowed for all file organ- 
izations. Variable with fixed-length control records are allowed in sequential 
and relative files only. 


You need specify the format only when you create a file. Thereafter, each time 
you open the file PL/I determines the format of the records in the file. 


9.3.1 Fixed-Length Records 


In a file containing fixed-length records, all records have the same length. 
When you create a file with fixed-length records, you must specify the length 
of each record in the file; this size cannot be changed thereafter. 


To create a file with fixed-length records in a PL/I program, use the FIXED_ 
LENGTH_RECORDS option of the ENVIRONMENT attribute. The 
MAXIMUM_RECORD_SIZE option specifies the size of each record. For 
example: | 
DECLARE FIXED_FILE FILE RECORD KEYED OUTPUT 

ENVIRONMENT ¢ 
FIXED LENGTH RECORDS 
MAXIMUM RECORD SIZE(80)33 
When the file FIXED_FILE is opened, its record format is established as 
having fixed-length 80-character records. 


When a file that has fixed-length records is processed by READ and WRITE 
statements, the file system checks the length of the variable specified in the 
INTO or FROM option to see if it is the same as the length of the records in 
the file. If not, the ERROR condition is signaled. 


When you process a file with fixed-length records, you can specify the 
SCALARVARYING option of ENVIRONMENT to process records in the 
standard PL/I manner. For an example of using the SCALARVARYING op- 
tion, see Section 6.2.48, “SCALARVARYING Option.” 


9.3.2 Variable-Length Records 


In a file consisting of variable-length records, each record can have a different 
size. RMS places a count field at the beginning of each record to indicate its 
size; however, this count field is not considered a part of the data record, nor 
is the length of the count field included in the size of the record. 
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9.4 Carriage Control 


VAX-11 PL/I provides a default carriage control for files that will be printed. 
This format, called carriage return format, may be specified in the ENVI- 
RONMENT option list with the CARRIAGE.__RETURN_FORMAT option; 
this option is never required. 


When a file has carriage return format, the file can be output to a printer or 
terminal on a record-by-record basis. On output, each record is automatically 
preceded by a line feed (<LF>) character and followed by a carriage return 
(<CR>) character; these characters are not stored in the record. Thus, each 
record in the file occupies one line of output. This type of carriage control is 
valid for any file or record organization. 


An alternate form of carriage control, called PRINTER_FORMAT, provides 
more explicit control of the output format and printing. Using printer format, 
you can specify such things as overprinting, skipping multiple lines, and so 
on. In a PL/I program, you will almost never need to use printer format; the 
PUT statement provides the same functions when it outputs data to a file 
with the PRINT attribute. 


For details on using printer format, see Section 6.2.36, “PRINTER — 
FORMAT Option.” 


9.5 Physical Organization of Stream Files 


In a PL/I program, the GET and PUT statements can access only files that 
have the STREAM attribute. A file has the STREAM attribute if: 


e The file was declared explicitly with a DECLARE statement and the 
STREAM attribute. Or, the file was declared explicitly with a DECLARE 
statement and with neither the STREAM nor the RECORD attribute. 


e The file was specified in and opened implicitly by a GET or PUT statement. 


Files that are declared with the STREAM attribute have the following char- 
acteristics: 


e Sequential organization of records. 


e Variable-length records, with the maximum length of either 132 (default) or 
the length defined by the LINESIZE option. 


e When the attributes STREAM, OUTPUT, and PRINT appear in the same 
declaration, a fixed control area that contains formatting information for 
the output file (see ‘Print File’ and “PRINT Attribute” in the VAX-11] 
PL/I Encyclopedic Reference). 


Stream files contain only ASCII data. The ASCII format used to represent 
program data in a stream output file differs depending on the attributes given 
to the file. For example, the representation of character strings differs depend- 
ing on the presence or absence of the PRINT attribute in the file declaration. 
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Chapter 10 
Sequential Files 


This chapter shows examples of some typical sequential file input/output 
operations on sequential disk files and on sequential devices, including mag- 
netic tapes. 


10.1 Creating a Sequential File 


Whenever a PL/I program opens a file with the SEQUENTIAL OUTPUT 
attributes, VAX-11 PL/I normally creates a new sequential file. By default, 
records are 510-byte variable-length records. Each WRITE statement adds a 
new record to the file. | 


10.1.1 Appending Records to an Existing File 


In VAX-11 PL/I, you can open a file with the APPEND option of ENVIRON- 
MENT to add new records at the end of an existing sequential file. This 
overrides the default action of PL/I, which is to create a new version of an 
existing file when the existing file is opened for output. For example: 
OPEN FILE(BIRD FILE) GUTPUT SEQUENTIAL 

TITLE( ‘BIRDS.DAT’) ENV( APPEND) 3 
WRITE FILE(BIRD FILE) FROM (NEWDATA)? 
This OPEN statement opens the file BIRD_FILE and positions it at its 
current end-of-file. The WRITE statement adds a new record at the end of the 
file. 


10.1.2 Superseding an Existing File 


_ The VAX-11 PL/I ENVIRONMENT option SUPERSEDE lets you create a 
new version of a file each time you write it, deleting an existing version. By 
default, each time a specific file is written, VAX-11 PL/I gives it a new 
version number and does not replace the existing version. For example: 


QPEN FILECCONTROL) OUTPUT RECORD TITLE( ‘CONTROL. BAT#:1°3 
ENVIRONMENT (SUPERSEDE) 5 


This OPEN statement opens the file CONTROL.DAT;1. If this file already 
exists, it is deleted. 
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10.2.2 Tape Positioning 


When an existing magnetic tape file is opened, it is by default rewound, if 
necessary, and positioned at its beginning. This positioning can be overridden 
in the following ways: 


e If the APPEND option of ENVIRONMENT is specified and if the file is 
opened with the OUTPUT attribute, the tape is wound and positioned at 
the end of the specified file. The next WRITE statement adds a new record 
at the end of the existing file. 


¢ The CURRENT_POSITION option of ENVIRONMENT causes the tape 
to remain at its current position when the next file is opened. Thus, if the 
file is in the middle of the tape, it is not rewound when the next OPEN 
statement is specified for the tape. 


By default, when a file is closed, the tape remains positioned following the last 
record that was read or written. The ENVIRONMENT option REWIND_ 
ON_CLOSE can override this action and position the tape at its beginning. 


While the file is open, the program can call the REWIND built-in subroutine 
to rewind the tape to its beginning. 


For example: 
DECLARE TAPEFILE FILE} 


OPEN FILE (TAPEFILE) OUTPUT RECORD ENVIRONMENT (APPEND) 3 
WRITE FILE (TAPEFILE) FROM (NEWREC) 3 


4 


CLOSE FILE¢TAPEFILE) ENVIRONMENT (REWIND ON CLOSE) 3 
OPEN FILE(TAPEFILE) INPUT RECORDS 


In this example, the file TAPEFILE is opened for output with the APPEND 
option. WRITE statements add new records at the end of the tape file. Then, 
the CLOSE statement specifies that the tape is to be rewound, and the next 
OPEN statement opens the file for input. The first READ statement reads the 
first record in the file. 


10.2.3 Blocking a Magnetic Tape File 


On a magnetic tape, a block is a unit consisting of an integral number of 
records. Because of the control information needed to separate records on a 
tape, operations on a tape can be improved by blocking. 


To create a blocked tape file, you must open it with the ENVIRONMENT 
option BLOCK_SIZE. This option specifies the size of the blocks. RMS 
automatically performs the blocking necessary. For example: 
OPEN FILE(TAPEFILE) ENVIRONMENT ¢ : 

BLOCK_SIZE (2048), 

MAXIMUM_RECORD SIZE (S1z2)+ 

FIXED_LENGTH RECORDS) 3 
WRITE FILE(TAPEFILE) FROM (BIG_RECORD) 3 


Following this open, each WRITE statement writes a single record; the file 
system buffers the records until it accumulates four records and transfers 
them, blocked, to the tape volume. 
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e When a file that spans two or more volumes is being read and the tape 
reaches end-of-tape, the magnetic tape ACP sends a message to the system 
operator requesting the operator to mount the next tape in the volume set. 


A PL/I program can request that the next volume in a volume set be mounted, 
for either an input or an output operation, by calling the NXTVOL built-in 
subroutine. The NXTVOL subroutine is described in Chapter 8, “File-Han- 
dling Built-In Subroutines.” 


The physical process of volume switching, whether the switching is performed 
automatically by RMS or as a result of a call to the NXTVOL built-in subrou- 
tine, is transparent to the PL/I program. As a user, you may wish to function 
as an operator to receive the volume switching requests and to mount the 
volumes yourself. For a description of the procedure for handling volume 
switching, see the VAX/VMS Command Language User’s Guide. 


10.3 Allocated and Spooled Devices 


VAX/VMS spools low-speed input/output devices such as printers by accu- 
mulating data for the device in a file, and then queueing the file for processing 
when it is closed. 


In a PL/I program, when you specify a device name such as LPAO: in a TITLE 
option, the specified device may be currently allocated for use by another user 
or be spooled. Depending on the status of the device, the following can occur: 


e If the device is spooled, all output to the device is written to a temporary 
file. When the file is closed, it is submitted to the queue for the spooled 
device. 


e If the device is allocated to another user, the UNDEFINEDFILE condition 
is signaled. If referenced in an ON-unit for this condition, the ONCODE 
built-in function returns the value associated with the status code 
SS$_DEVALLOC. 


e If the device is allocated to the current process, PL/I assigns a channel to 
the device and each WRITE statement writes a physical line to the device. 


e If the device is not allocated and is not spooled, PL/I assigns a channel to 
the device. This assignment performs an explicit allocation of the device to 
the current process. 


You can allocate a device before running a program by issuing the DCL 
command ALLOCATE. Within a PL/I program, you can invoke the system 
service SYS$ALLOC to allocate a device. For information on commands for 
device allocation and control, see the VAX/VMS Command Language User’s 
Guide. For information on allocating devices using the SYS$ALLOC system 
service, see the VAX/VMS System Services Reference Manual. 
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Chapter 11 
Relative Files 


This chapter describes considerations for creating and using relative files and 
shows examples of some typical relative file input/output operations. 


11.1 The Organization of a Relative File 


The relative file organization is suitable for files with data that can be ar- 
ranged serially and uniquely identified by an integer value, for example, a 
part number or an employee identification number. Within the file, records 
are written into cells that are numbered. There is a one-to-one correspondence 
between the cell number and the integer value associated with the data in the 
record. This number is called the relative record number; the relative record 
number is the key by which records are written and accessed. 


Figure 11-1 illustrates a relative file in which not all cells contain records. The 
first record written to the file was relative record number one (which may 
have been data for a part numbered one or an employee whose number is one, 
for example). The second record written was relative record number two. The 
third record written was relative record number four; thus cell number three 
does not contain a record. 


CELL 
NUMBERS 1 2 3 


4 
record 7p 
1 2 






SS 





FIRST SECOND THIRD 
RECORD RECORD RECORD 
WRITTEN WRITTEN WRITTEN 


Figure 11-1: A Relative File 


Although the cells in a relative file have the same length, the records need not 
be fixed-length records. However, when a record is smaller than the length of 
a cell, the unused space is wasted. 


11.2.2 Record Size 


When you specify the length of the records in a file, RMS uses the value you 
specify in the MAXIMUM_RECORD_SIZE option to calculate a cell size. It 
uses the following formulas to calculate the size: 


Fixed-Length Records 
cell-size = 1 + record-size 


One byte is required for overhead; this byte contains a deletion indicator. 


Variable-Length Records 
cell-size = 3 + maximum-record-size 


Three bytes are required for overhead; two bytes for the individual record size, 
and one byte for a deletion indicator. 


When you select a record size for a relative file, you should try to specify a size 
that is no greater than the largest record that will be written. Otherwise, any 
unused space in each cell will be wasted. If you do not specify a maximum 
record size for either fixed- or variable-length records, VAX-11 PL/I uses the 
default length of 480 bytes. 


11.2.3 Bucket Size 


A bucket is the storage unit for data in the file. Records are arranged 
in buckets, which consist of an integral number of physically contiguous 
512-byte disk blocks. Within the bucket, records can cross block boundaries; 
however, records cannot cross bucket boundaries. 


When VAX-11 RMS transfers data from a file, it transfers data a bucket at a 
time; thus, a large bucket size reduces the number of actual data transfers 
that are required. When you do not specify a bucket size, RMS uses the cell 
size rounded to a multiple of 512 bytes. When records are written to the file, 
RMS places as many records as will fit in each bucket. Excess space is wasted. 


You can improve I/O performance by specifying a bucket size that is a multi- 
ple of the cell size, and doing some simple calculations to determine whether 
space is being wasted. For example: 
DECLARE EMP_FILE OUTPUT RECORD ENVIRONMENT (¢ 

FIXED_LENGTH RECORDS + 


MAXIMUM_RECORD_SIZE (80) 
BUCKE FSi 2E hah). 05 


In this example, the file EMP_FILE will be created with 81-byte cells and 
buckets that are 2048 bytes (that is, four 512-byte blocks). Each bucket can 
contain 25 81-byte cells; 23 bytes in each bucket are unused. 


When you specify a maximum record size and a bucket size for a relative 
file, you should consult the description of the BUCKET_SIZE option in 
Chapter 6, “ENVIRONMENT Options.” That description contains formulas 
for calculating the bucket size within the limits required by RMS. 
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The following notes are keyed to Sample Program 11-1: 


1. The structure PARTLIST describes the layout of the records in the file. 
| The records will be ordered in the relative file according to part number, 
that is, using the field PARTLIST.NUMBER. 


2. The file OLDFILE is the sequential file containing the records to be cop- 
ied to a relative file. When the end-of-file is reached, the STOP statement 
terminates the program. 


3. The relative file PARTS is declared with a maximum record number of 
600. It has fixed-length, 38-byte records. 


4. As each record is read into the structure PARTLIST, the value of 
NUMBER is copied to the fixed binary integer RECORD_NUMBER. 
The part number is maintained in each record in its character-string form. 


5. Each WRITE statement copies the record to the output file, specifying the 
value of the part number as a relative record number. 


Records in this file can subsequently be accessed either sequentially or by part 
number. To access a record by part number, you specify the number as a key. 
For example: 


GET LISTCINPUT NUMBER?) OPTIONS(PROMPTi ’Part? %3335 
READ FILECPARTS) INTOCPARTLIST) KEY(INPUTUNUMBER?: § 


Here, the value entered in response to the GET statement is used as a key 
value to access a record in the file. 


11.3.1 Populating a Relative File 


In the example in the preceding section, the file PARTS is created by the 
opening of the file with the KEYED and OUTPUT attributes. When this 
program executes, the amount of space allocated for the file PARTS depends 
on the relative record numbers of the records that are written to the file. For 
example, if the largest record number specified for any record in the file is 600, 
but the largest record number specified for a record is 200, then RMS allocates 
only as much space as is needed for 200 records. 


When you initially populate a file and you plan to fill the entire file, through 
the maximum record number, you can cause RMS to allocate space for the 
entire file using either of the following techniques: 


e Specify the FILE_SIZE option to allocate space for the file when it is 
created, as described in Section 11.2.4, ‘‘File Size.” 


e Write the record with the largest relative record number first. This will force 
RMS to allocate space for the entire file. 


These techniques can optimize the throughput for the subsequent file addi- 
tions, since RMS will not need to perform repeated extensions to the file as 
records are added. 
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11.3.4 Error Handling 


PL/I signals the KEY condition when errors occur while processing record 
numbers for relative files. For example, it signals the KEY condition when a 
relative record number exceeds the maximum record number specified for the 
file, or when the number of a record that already exists is specified in a 
KEYFROM option in a WRITE statement. 


The sample ON-unit below shows how to detect whether a record already 
exists in a relative file or whether a record number specified exceeds the file’s 
maximum record number. 


ON KEY(PARTS) BEGINS 
DECLARE (RMS# REX: RPMS MRN) GLOBALREF FIXED BINARY (31) VALUES 
/# Check for duplicate records #/ 
IF ONCODE() = RMS#.REX THEN BOS /# if duplicate #/ 
PUT SKIP EDIT(’Part number’ + 
PARTLIST.NUMBER; ‘exists. Reenter} 
(AsKs+ArXsAdS 


GET LIST(CPARTLIST.NUMBER?) 5 /® Get new value #/ 
GOTO GETUDATAS /*%® Go get other data #/ 
END 5 

f# Check for maximum record number exceeded #/ 


ELSE IF ONCODE = RAMS&.MNRN THEN DOS 
PUT SKIP EDIT{ ‘Part number’ -PARTLIST.NUMBER: 
‘invalid. Reenter‘) 
fAsrksAsK-Ald sd 


GET LIST(¢PARTLIST.NUMBER) 5 /® Get new value #/ 
GOTO GET.DATAS /* Go get ather info #/ 
END 3 


END 3 


GET.DATA: 


In this example, the ON-unit declares symbolic names for two specific status 
values returned by ONCODE: 


e The value RMS$_REX indicates that a record already exists. 


e The value RMS$_MRN indicates that a relative record number specified 
exceeds the maximum record number. 


In an ON-unit for the KEY condition for a relative file, ONCODE may also 
return the values associated with the following status codes: 


e RMS$_RNF, which indicates that there is no record in the file with the 
relative record number specified by a KEY option. 


¢ RMS$_KEY, which indicates that a key value is invalid, for example, if it 
is not an integer. 


The symbolic names for these status codes must be declared with the 
GLOBALREF and VALUE attributes because the names are defined as 
global symbols by the VAX/VMS system. For more information on defining 
symbols and using symbols in ON-units, see Chapters 15, “Global Symbols,” 
and 17, “Error and Condition Handling.” 
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Chapter 12 
Indexed Sequential Files 


This chapter describes considerations for creating and using indexed files and 
shows examples of some typical operations on indexed sequential files. 


12.1 Indexed File Organization 


In an indexed sequential file, the file contains data records and pointers to the 
records. Data records and record pointers are arranged in buckets, which 
consist of an integral number of physically contiguous 512-byte disk blocks. 


Individual records within the file are located by the specification of the keys 
associated with the records. Each file must have a primary key; this is a field 
within the record that has a unique value to distinguish it from all other 
records in the file. An indexed sequential file can also have up to 254 alternate 
keys, which need not have unique values. 


As RMS writes records to an indexed file, it writes them in collating sequence 
according to the primary key, in buckets that are chained together. Thus, the 
file can be accessed sequentially using any key. 


Figure 12-1 illustrates an indexed sequential file with a single key, or index. 


12-1 


The records in the file illustrated in Figure 12-1 consist of address data that 
might have been defined in a PL/I structure as follows: 
DECLARE 1 ADDRESS.FILE: 
2 EMPLOYEE.NAME CHARACTER (30) + 
2 ADDRESS: 
9 STREET THARACTER (2075 
3 ZIPCODE CHARACTER(5)3 


In this file, the key is the employee name. 


When RMS writes records to an indexed sequential file, it builds and main- 
tains a tree-like structure of key value and location pointers. When records are 
accessed by key, RMS uses the tree to locate individual records. Thus, when a 
PL/I program wants to access the record whose key value is JONES, RMS 
traverses the indexes to locate the record. 


When new records are added to an indexed sequential file, a data bucket may 
not have enough room to accommodate a new record. In this case, RMS 
performs what is called bucket splitting — it inserts a new bucket in the chain 
of data buckets and moves enough records from the previous bucket to pre- 
serve the primary key sequence. Bucket splitting is transparent to the PL/I 
program; the program only knows that it has added a record to the file. 


12.2 Creating an Indexed Sequential File 


To create an indexed sequential file for VAX-11 PL/I, you must use the 
RMS-11 utility program DEFINE. After you create the file, you can use PL/I 
to populate the file by opening it with the UPDATE attribute and using 
WRITE statements to write records to it. 


To invoke the DEFINE utility, enter the following command: 
$ MCR DEF 


This command invokes the RMS-11 utility by its task name, DEF. This 
utility is interactive: it prompts you to enter data and responds with error 
messages when you enter data incorrectly. It also provides information when 
you enter a question mark (?) in response to any of its prompts. 


The short example below shows how to create the indexed sequential file that 
contains the records for the address file in Figure 12-1. The file will be named 
ADDRESS.DAT, and its character-string key field will be defined as the 
first 30 bytes of each record. Note that the only information that you 
must specify is: 


e The file specification of the file you are creating 

e IDX, to indicate that the file is an indexed sequential file 
e The position of the key within the file’s records 

e The size of the key 
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12.3 Defining Keys 


An indexed sequential file must have at least one key. It can have up to 255 
keys; however, for file processing efficiency it is recommended that no more 
than seven or eight keys be defined. The time required to insert a new record 
or update an existing record is directly related to the number of keys defined. 
The retrieval time for an existing record is unaffected by the number of keys. 


When you design an indexed sequential file, you must define each key in the 
following terms: 


e The position and size of the key 
e The data type of the key 

e The index number of the key 

e Key options selected for the key 


In the example in the preceding section, only one key is defined, beginning in 
the first field of the record. However, when you want to define more than one 
key, or to define keys of different data types, you must be careful when you 
specify the key fields. The next few subsections describe some considerations 
for specifying keys. 


12.3.1 Specifying Key Position and Size 


When you specify a key, you must specify its position in the record and its 
length. The position must be specified with respect to the beginning of the 
record — thus, a key that is positioned beginning in the first byte of the record 
has a starting position of 0, a key positioned beginning in the 21st byte has a 
key position of 20, and so on. 


To determine the key positions for fields within a structure, you can examine 
the storage map in the program listing that defines the structure. Figure 12-2 
illustrates the relationship between the key field definitions and the storage 
map offsets. 


Indexed Sequential Files 12-5 


The keys in Figure 12-2 can be specified as follows for DEFINE: 


IT’S TIME TO DEFINE THE PRIMARY KEY 
ENTER DATA TYPECSTR) = @ED 

ENTER POSITION OF KEY: 0@E <— 

ENTER SIZE OF KEY: 20@ED <— 

ENTER NAME OF KEY (NONE) : @ED 

WILL YOU ALLOW DUPLICATE KEYS(NOQ) ?@ED 


DO YOU WANT TO DEFINE MORE KEYS(NOI?FYR@ED <— 
ENTER DATA TYPE(CSTR) « GED 

ENTER POSITION OF KEY:116@) <— 

ENTER SIZE (OF KEY sS0RE) <— 

ENTER NAME OF KEY (NONE) s QED 

WILL YOU ALLOW DUPLICATE KEYS( YES)? @ED 

WILL YOU ALLOW KEYS TO CHANGE C YES)? @ED 

DO YOU WISH TO DEFINE A NULL KEY VALUE (NO) 7 @ED 


JUST FINISHED ALTERNATE KEY NUMBER 1 

DO YOU WANT TO DEFINE MORE KEYS(NO} FYRED <— 
ENTER DATA TYPE(STR) s RED 

ENTER POSITION OF KEY: 14G6@ED <— 

ENTER SIZE OF KEY: 30@E) <— 

ENTER NAME OF KEY (NONE) : RED 

WILL YOU ALLOW DUPLICATE KEYS( YES) ? @eD 

WILL. YOU ALLOW KEYS TO CHANGE( YES)? @eD 

DO YOU WISH TO DEFINE A NULL KEY YALUE NO) FRED 


JUST FINISHED ALTERNATE KEY NUMBER 2 
DO YOU WANT TO DEFINE MORE KEYS(NO)?Y@) < 
ENTER DATA TYPE(STR):INT@D < 

ENTER POSITION OF KEY:20@ < 

ENTER SIZE OF KEY:4@ < 

ENTER NAME OF KEY (NONE) : GD 

WILL YOU ALLOW DUPLICATE KEYS( YES)? @ 

WILL YOU ALLOW KEYS TO CHANGE( YES) ?@ 

DO YOU WISH TO DEFINE A NULL KEY VALUE(NO) ?@ED 


JUST FINISHED ALTERNATE KEY NUMBER 3 
BO YOU WANT TO DEFINE MORE KEYS(NO}PN@ED <— 


After all the keys are defined (that is, ‘“‘N’’ is entered in response to the last 
question above), DEFINE begins prompting for file placement and allocation 
information, and then prompts for file protection information. You can press 
to answer all prompts. Or, you can study the file’s requirements and 
specify placement and allocation information using the guidelines described 
in the RMS-11 User’s Guide. 


12.3.2 Key Data Types 


Table 12-1 summarizes the valid data types for keys in VAX-11 RMS indexed 
sequential files, lists the corresponding PL/I data type declaration, and shows 
how to specify the key data type and length to the DEFINE utility. 
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12.3.4 Key Options 


When you define alternate indexes for an indexed sequential file, you can 
specify: 


e Whether duplicate keys are allowed. If you select the duplicate key option, 
multiple records in the file can have the same key value in the alternate 
index. If you do not allow duplicate keys, PL/I signals the KEY condition if 
you attempt to write a record with a duplicate key. 


e Whether the key of a record can be changed. If you select the change option, 
a rewrite request can modify one or more key fields in the record. By de- 
fault, PL/I signals the KEY condition if you attempt to rewrite a record in 
which a key field has been modified. 


e Whether Keys are to be initialized with null values. When a null value has 
been specified for a key and a record is inserted with the given key field 
equal to the null value, no index entry will be made in that alternate index. 


These options are described in the RMS-11 User’s Guide. 


12.4 Using Indexed Sequential Files 


After you have created an indexed sequential file with the DEFINE utility, 
you can write records to it by opening it with the UPDATE attribute and 
using PL/I WRITE statements. For example: 


OPEN PILECSTATELPILE) RECORD DIRECT UPDATE's 


WRITE FILECSTATE_FILE} FROM¢STATE) KEYFROM(STATE.NAME? 3 


This WRITE statement writes the record whose key value is specified by the 
field STATE.NAME in the structure STATE. 


When a WRITE statement adds a record to an indexed sequential file, the 
value of the KEYFROM option must always be the primary key. In fact, the 
WRITE statement causes the index number to be reset to zero if any other 
index number is in effect. 


Indexed Sequential Files 12-9 


12.4.3 Accessing Records by Alternate Key 


To read a record in an indexed sequential file using an alternate key, specify 
the INDEX_NUMBER option on a READ statement. For example, to access 
the record for a state whose flower is MAGNOLIA, the following statements 
could be written: 

OPEN FILE(STATE.FILE) KEYED INPUT$ 


READ FILE(STATE_FILE) SET(STATE.PTR) KEY(‘MAGNOLIA‘) 
OPTIONS (INDEX NUMBER(1))§ 


The INDEX_NUMBER option specifies the first alternate index, the 
FLOWER field. The INDEX_NUMBER option is also valid on the 
REWRITE and DELETE statements. 


You can access a file starting with an alternate index by opening the file with 
the INDEX_.NUMBER ‘option of ENVIRONMENT. For example: 


OPEN FILE(STATE_WFILE)} SEQUENTIAL INPUT ENE 
INDEX UNUMBER (2335 

READ FILECSTATE_LFILE)} SET(STATE_PTR) 3 
DO WHILE ¢€"EQF) 5 

PUT SKIP EDIT(STATE-.BIRD: ‘is the bird of ‘-:STATE.NAMNE) 

(Ark sArH + Ada 
READ FILE(STATE_FILE)} SETI(STATE_LPTR) : 
END 5 


These statements, executed until the end-of-file is reached, access the records 
in the file STATE__FILE based on its second alternate index, the BIRD field. 


12.4.4 Updating Records in an Indexed Sequential File 


You can modify records in an indexed sequential file by opening the file with 
the UPDATE attribute and using REWRITE and DELETE statements to 
modify or delete records from the file. 


The following example shows the correction of an invalid field in a record in 


the file STATE__FILE: 
DECLARE (STATENAME;NEWNAME) CHARACTER(30) VARYING 


+ 


OPEN FILE(STATE_LFILE)} KEYEG SEQUENTIAL UPDATE: 
GET SKIP LIST(STATENAME) OPTIONS(PROMPT( ‘States: ‘335 
READ FILECSTATE_FILE) SET(STATE_PTR)} KEY(STATENAME) § 
GET SKIP LIST(NEWNAME) OPTIONS ¢ 

PROMPT( ‘New state flower names “135 
STATE.FLOWER = NEWNAME 5 
REWRITE FILE¢STATE_WFILE:) 3 


The REWRITE statement rewrites the current record in the file, that is, the 
record that was just read with the READ SET statement. 
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ON KEY(STATE_LFILE)} BEGIN: 
DECLARE (RMS ANF: FMS. DUP) GLOBALREF FIXED BINARY( 31) VALUE: 
/*® Check for a record not found #/ 
IF ONCOBDE() = RMS#.0RNF THEN G05 “#2 if record not found #7 
PUT SKIP EBIT(STATENSME: ‘Not found. (34 
(ArKsAlS 
STOP § 
END § 
f* Check for duplicate Key #/ 
ELSE IF ONCODE = RMS#_BDUP THEN DOS 
PUT SKIP EDIT( ‘Record already exists for’ > STATENAME} 5 
(AsKsA2 4 
STOP 3 
END 4 
END 4 


In this example, the ON-unit declares symbolic names for two specific status 
values returned by ONCODE: 


e The value RMS$_RNF indicates that no record exists with the specified 
key value. 


e The value RMS$_DUP indicates that a record already exists with the spec- 
ified key in an index for which duplicate keys are not allowed. 


In an ON-unit for the KEY condition, ONCODE may also return the value 
associated with the status code RMS$—_KEY, which indicates that a key 
value is invalid, for example, if it is an incorrect data type. 


The symbolic names for RMS status codes must be declared with the GLO- 
BALREF and VALUE attributes because the names are defined as global 
symbols by the VAX/VMS system. For more information on defining symbols 
and using symbols in ON-units, see Chapters 15, “Global Symbols,” and 17, 

“Error and Condition Handling.” | 
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Chapter 13 
File Protection and File Sharing 


This chapter provides examples of using ENVIRONMENT options to take 
advantage of special processing options of RMS. It includes discussions of: 


e File protection 


e File sharing 


13.1 File Protection 


Each user who is authorized to use the system is assigned a UIC (User Identi- 
fication Code) by the system manager. When a PL/I program creates a file, 
the current UIC associated with the process executing the program defines the 
file’s ownership. 


Based on this UIC, called the owner UIC, the file system defines the protec- 
tion of the file in terms of (1) which other users on the system can access the 
file and (2) what operations they can perform on the file. The other users in 
the system are defined as follows: 


¢ Owner. Any other process that has the same UIC as that established as the 
file’s owner is also the owner of a file. 


e Group. A process that has the same group number in its UIC is a member of 
the owner’s group. 


e System. A process that has a group number in the system-defined range or — 
that has the SYSPRV user privilege is in the system user category. 


e World. All jobs and processes that do not fall into the other three categories 
belong to the world category. 
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13.1.2 Defining a File’s Protection 


When you specify ENVIRONMENT options for a file you are creating in a 
PL/I program, you can specify the following options to define the access per- 
mitted to various users: 


OWNER_PROTECTION 
GROUP_PROTECTION 
SYSTEM PROTECTION 
WORLD_PROTECTION 


These options specify the types of access permitted by the specification of the 
following codes 


e R — gives the right to read the file. 
e W — gives the right to modify the file. 


e EK — gives, for files containing executable program images, the right to 
execute the program. 


e D — gives the right to delete the file. 


These codes can be specified in any order for an option; if you specify an 
option and omit a code, that category of user is denied that type of access. If 
you specify one or more protection options, the protection for categories you 
do not specify defaults to no access. If you do not specify any protection 
options, then PL/I uses the current default protection for all the categories. 


For example: 


ENVIRONMENT ¢ 
OWNER_LPROTECTION (¢ ’RHE ‘3 
SYS rer. PROTECOLION: 4°73 
GROUPLPROTECTION( ’R?33 


This specification defines protection to a file as follows: 


e The OWNER_PROTECTION option specifies RWE, that is, read, write, 
and execute access. Because D is not specified, the owner is not allowed 
delete access and thus cannot inadvertently delete the file. 


e The SYSTEM_PROTECTION and GROUP__PROTECTION options 
specify only read access for system and group users. 


e The WORLD_PROTECTION option is not specified; this denies all access 
to all users who are in the world category. 


Note that the DCL command SET PROTECTION allows the owner of a file 
to change the file’s protection at any time. Additional commands and user 
privileges allow the protection of a file to be overridden or changed. For details 
on these commands and privileges, see the VAX/VMS Command Language 
User’s Guide. 


The file system applies the protection you specify for a file when the file is 
accessed from a program or from the DCL command level. It also applies the 
protection when the file is to be shared, as described in the next section. 
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of the file. Other processes may access the file only for reading; they must 
specify SHARED_WRITE, to indicate that they allow writing of the file 
while they are reading it. 


If SHARED_WRITE is specified, processes that subsequently access the file 
with the SHARED_WRITE option may write the file. 


Both the SHARED__READ and SHARED_WRITE options may be specified 


for a file. 


Table 13-1 summarizes the effects of opening a file with file-sharing options. 


Table 13-1: Effects of File-Sharing Options 


Open Option 
and Access 
Specified by 
First Opener 


ENV(NO_SHARE) ! 
INPUT, OUTPUT, 
or UPDATE 


ENV(SHARED__READ) 
INPUT 


ENV(SHARED__READ) 
OUTPUT or 
UPDATE 


ENV(SHARED_WRITE) 
INPUT 


ENV(SHARED__WRITE) 
OUTPUT or 
UPDATE 


Open Option 
Specified by a 
Subsequent Opener 


ENV(NO__SHARE) 
ENV(SHARED__READ) 
ENV(SHARED_WRITE) 
ENV(NO__SHARE) 


ENV(SHARED__READ) 
ENV(SHARED_WRITE) 


ENV(NO__SHARE) 


ENV(SHARED__READ) 
ENV(SHARED_WRITE) 
ENV(NO__SHARE) 
ENV(SHARED__READ) 
ENV(SHARED__WRITE) 


ENV(NO__SHARE) 


ENV(SHARED__READ) 


ENV(SHARED_WRITE) 


Access Allowed 
Subsequent Opener 


None. The UNDEFINED- 
FILE condition is signaled? 


None. The UNDEFINED- 
FILE condition is signaled? 


The file is accessed for input 


The UNDEFINEDFILE 
condition is signaled? 


None. The UNDEFINED- 
FILE condition is signaled? 


None. The UNDEFINED- 
FILE condition is signaled” 


The file can be accessed for 
input only 


The UNDEFINEDFILE 
condition is signaled? 


The file can be accessed for 
input, output, or update 


The file can be accessed for 
input, output, or update 


None. The UNDEFINED- 
FILE condition is signaled? 


None. The UNDEFINED- 
FILE condition is signaled” 


The file can be accessed for 
input, output, or update 





1. You must have write access privilege to open the file with the NO__SHARE option. 
2. ONCODE returns the value for RMS$__FLK. See Section 13.2.2, “‘File Locking.” 
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A record is locked when both of the following are true: 
e A READ statement is issued for the record. 


¢ The file containing the record was opened with the OUTPUT or UPDATE 
attribute. 


A record remains locked until one of the following occurs: 


e The locked record is rewritten or deleted. 


e A READ, WRITE, REWRITE, or DELETE statement is executed to access 
another record in the same file. 


e The REWIND built-in subroutine is called to rewind the file to its begin- 
ning. 


e The file is closed. 


Records are also locked for the duration of aWRITE, REWRITE, or DELETE 
statement to ensure that the I/O completes. The records are unlocked when 
these statements complete. 


If a procedure in another process attempts to access a record that is locked, 
the ERROR condition is signaled. In an ON-unit that executes following this 
condition, a reference to the ONCODE built-in function returns the value 
associated with the RMS status code RMS$_RLK (meaning that the record 
is locked). 


Thus, a file-sharing application can test whether a record in a file is currently 
locked in an ON-unit, as in the following example: 


ON ERROR BEGINS 
DECLARE RMS$.RLK GLOBALREF FIXED BINARY(31) VALUES 


IF ONCODE() = RMS#_ RLK THEN CALL RECORDSYNC;: 
ELSE CALL RESIGNAL() 5 
END 4 


The ON-unit in this example tests whether any ERROR condition is signaled 
as a result of attempting to access a locked record. If so, it calls a procedure 
that will synchronize with the other process reading the record. Otherwise, 


it calls the RESIGNAL built-in subroutine to perform default condition 
handling. 
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Part III 
Procedure Calling and Condition Handling 


Chapter 14 
Argument Passing 


The architecture of the VAX-11 defines a set of conventions for passing argu- 
ments among procedures. These conventions make it possible for procedures 
that are written in PL/I to invoke, with a CALL statement or with a function ° 
reference, procedures written in other programming languages, for example 
FORTRAN, PASCAL, and assembly language. These conventions are known 
as the VAX-11 Calling Standard. 


This chapter describes the calling standard and the argument-passing mecha- 
nisms defined in it, and explains the VAX-11 extensions to the PL/I language 
that support it. 


This chapter assumes a knowledge of the PL/I conventions and rules for 
passing arguments to external procedures, as described in the VAX-11 PL/I 
Encyclopedic Reference under the heading “Parameters and Arguments.” Al- 
though the argument-passing structures used by the system are transparent to 
your PL/I programs, they are presented in this chapter (in a simplified for- 
mat) to provide you with the necessary background to write calls to non-PL/I 
procedures. 


14.1 The Call Stack 


A call stack is a temporary area of storage that the system allocates for each 
user process. On the call stack, the hardware maintains information about 
each block activation in the current image. 


14.1.1 Call Frames 


Each time a procedure block is activated in a PL/I program, the hardware 
creates a structure on the call stack. This structure is the call frame for the 
procedure invocation. The call frame for each active procedure contains: 


e A pointer to the call frame of the previous block activation. This pointer is 
called the Frame Pointer (FP). 


e The saved Argument Pointer (AP) of the previous procedure invocation. 


e The address in storage of the point of invocation of the procedure, that is, 
the address of the next instruction following the CALL instruction or CALL 
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Argument Pointer (AP) 






n = argument count 


bits 4 through 31 
DIGITAL 


argument_n 


Figure 14-2: An Argument List 


The calling standard defines three ways that data can be passed in an argu- 
ment list. When you are coding a reference to a non-PL/I procedure, you must 
note the mechanism by which each argument is to be passed and write the 
parameter descriptor for each argument accordingly. 


The three argument-passing mechanisms are: 


e By immediate value. When an argument is passed by immediate value, the 
actual value of the argument is present in the argument list. 


e By reference. When an argument is passed by reference, the address in 
storage of the argument is present in the argument list. 


e By descriptor. When an argument is passed by descriptor, the address in 
storage of a data structure describing the argument is present in the argu- 
ment list. 


Sections 14.2 through 14.4 describe these argument-passing mechanisms in 
detail. These sections describe the arguments in terms of PL/I data types, 
dummy arguments created, if any, parameter-passing conventions, and at- 
tributes to define the manner in which parameters are to be passed. Figures 
14-3 through 14-6, which accompany these sections, illustrate these mecha- 
nisms. 


Remember that when PL/I creates a dummy argument, modifications, if any, 
that the called procedure makes to the dummy argument are not accessible to 
the caller. 


Note that most of the examples show calls to VAX/VMS system service proce- 
dures. These examples do not describe the procedures themselves. For general 
and specific descriptions of system services, see the VAX/VMS System Ser- 
vices Reference Manual. For additional details on calling system services from 
PL/I programs, see Chapter 19, “System Services.” 


14.2 Passing Arguments by Immediate Value 


You must use the VALUE attribute in a parameter descriptor for an argument 
to be passed by immediate value. The following declaration of the external 
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parameter descriptor is specified with the ANY and VALUE attributes, the 
data types of the dummy arguments that PL/I creates are: 


Data Type of Data Type of 
Written Argument Dummy Argument 
FIXED BINARY, or 

FIXED DECIMAL (p,0) FIXED BINARY (31) 
BIT or BIT ALIGNED BIT (32) ALIGNED 
ENTRY ENTRY 
OFFSET OFFSET 
POINTER POINTER 


If a parameter descriptor is specified as VALUE with a particular data type 
(as opposed to being specified as ANY), adummy argument of that data type 
is always created, and the written argument is assigned to the dummy. The 
written argument must be valid for conversion to the data type specified in 
the corresponding parameter descriptor. 


14.3 Passing Arguments by Reference 


By reference is the default argument-passing mechanism used by PL/I for all 
arguments except character strings and arrays with nonconstant extents. The 
parameter descriptor for an argument to be passed by reference need specify 
only the data type of the parameter. 


For example, the Read Event Flags (SYS$READEF) system service requires 
its first argument to be passed by immediate value and its second argument to 
be passed by reference. This procedure can be declared as follows: 


DECLARE SYS#READEF ENTRY (FIXED BINARY(31) VALUE: 
BIT (32) ALIGNED) 3 


When this procedure is invoked, the second argument must be a variable 
declared as BIT(32) ALIGNED. PL/I passes the argument by reference. Fig- 
ure 14-4 illustrates argument passing by reference. 


Argument Pointer (AP) 
pointer to variable 


DECLARE FLAGS BIT (32) ALIGNED; 


DECLARE SYS$READEF ENTRY ( 
FIXED BINARY(31) VALUE, 
BIT(32) ALIGNED ); 











CALL SYS$READEF(4,FLAGS); 
number of arguments: 





first argument: 


second argument: 


Figure 14-4: Argument Passing by Reference 
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a PL/I parameter descriptor with asterisk extents. In FORTRAN, arrays must 
always be passed by reference; the array’s extents are, by custom, passed as 
separate arguments. The ANY attribute provides a convenient way to express 
an array parameter for FORTRAN, as in the following example: 

FTNARRAY: PROCEDURE(X)$ 


DECLARE SUM ENTRY (ANY+s+ FIXED BINARY(313) 
RETURNS (FLOAT) 3 


DECLARE (S+ X(#)) FLOATS 
S = SUM(As DIM(X+1))5 


In this example, SUM is a FORTRAN procedure that sums the elements of a 
one-dimensional array of floating-point numbers. Its second parameter is the 
number of elements in the array. 


14.3.3.2 Dummy Arguments for Arguments Passed by ANY — When a param- 
eter that is declared with the ANY attribute but without the VALUE attrib- 
ute is associated with a written argument that is a variable, PL/I places the 
address of the actual variable in the argument list. If the procedure is invoked 
with a constant or expression for this argument, PL/I creates a dummy argu- 
ment and places the address of the dummy argument in the argument list. 


In creating a dummy argument, PL/I performs the conversions listed below: 


Data Type of Data Type of 
Written Argument Dummy Argument 
BIT (unaligned) BIT ALIGNED 
FIXED BINARY, or 
FIXED DECIMAL (p,0) FIXED BINARY (31) 
CHARACTER VARYING CHARACTER nonvarying 


In all other cases, the data type of the dummy argument is the same as the 
data type of the written argument. 


14.3.4 Using Pointer Values for Arguments Passed by 
Reference 


When an argument is passed by reference, PL/I places the address of the 
actual argument in the argument list. This address can be interpreted as a 
pointer value. In fact, you can explicitly specify a pointer value as an argu- 
ment for data to be passed by reference. For example: 
DECLARE SYS$READEF (ANY YALUE+s POINTER VALUED» 


FLAGS BIT(32) ALIGNED: 
CALL SYS$READEF (4+ ADDR(FLAGS))3 


At this procedure invocation, PL/I places the pointer value returned by the 
ADDR built-in function directly in the argument list. Figure 14-5 illustrates 
the argument list for this example. Note that the actual argument list in this 
example corresponds to the argument list shown in Figure 14-4. 
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DECLARE UNSTRING ENTRY (CHARACTER(C#) 3. \ 
TESTE LTS ENGR CBT ao es 
MODEST ENTRY (i+ 
& CHARACTER(C#) + 
3 BIT(3) + 
a BITC) 


_ Figure 14-6 illustrates a character-string descriptor and shows how a charac- 
ter-string argument is passed by descriptor. This example illustrates the type 


of character-string descriptor used by system services; this descriptor does not 
contain additional information required by other classes of descriptor. 


DECLARE NAME CHARACTER (5) 
STATIC INITIAL (‘ORION ‘); 

DECLARE SYS$SETPRN ENTRY 
(CHARACTER(*)); 





Argument Pointer (AP) 


pointer to descriptor 


ee ee 
pointer to variable 


CALL SYS$SETPRN(NAME); 






number of arguments: 


first argument: 







Figure 14-6: Argument Passing by Descriptor 


14.4.2 Passing Character Strings 


When you declare a non-PL/I procedure that requires a character-string 
descriptor for an argument, specify the parameter descriptor as CHARAC- 
TER(*). For example, the Set Process Name (SYS$SETPRN) system service 
requires the address of a character-string descriptor as an argument. You can 
declare this service as follows: | 


DECLARE SYS#SETPRN ENTRY (CHARACTER(#)25 


When a parameter is declared as CHARACTER(*), its written argument can 
be: 


e A character-string constant or expression 
¢ A fixed-length character-string variable 


e A varying character-string variable or a variable declared as 
CHARACTER(*) VARYING 


For any of these arguments, PL/I constructs a character-string descriptor and 
places its address in the procedure’s argument list. . 
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2. Declare a structure variable in your program whose members and attrib- 
utes correspond to the structure declared in the parameter descriptor for 
the argument. 


3. Assign values to the members of the structure variable providing the re- 
quired information. For a character-string descriptor, you must provide 
the length of the string and a pointer to the variable containing its value. 


4. Pass the name of the structure variable as an argument in the procedure 
invocation. 


The Set Process Name (SYS$SETPRN) system service shown in Figure 14-7 
requires a text name string to be passed by descriptor. The structure variable 
NAME_DESC is a character-string descriptor: its members describe the 
length and location of the character-string variable NEWNAME. The value of 
NEWNAME is the actual argument passed to the procedure. Note that the 
call in this example is equivalent to the example shown in Figure 14-6 of 
passing an argument by descriptor. 


DECLARE SYS#SETPRN ENTRY (1: 


hea Ped 


FIXED BIN Ass tage 
POINTER) 3 


DECLARE 1 NAME_DESC; 
© NAMELLENGTH FIXED BINARY (31): @ 
= NAME ADDRESS POINTER: 


DECLARE NEWNAME CHARACTER (3:3 STATIC INITIAL (’ORITOQN‘)3 
NAME_DESC.NAME_LENGTH = Plato a seb aaaEar 3 
NAME DESC.NAME_ADDRESS = ADDR(NEWNAME? : 


CALL SYS#SETPRN(NAME DESC): @ 

Figure 14-7: Coding a Character-String Descriptor 

Note that this example can be simplified by declaring SYS$SETPRN as 
follows: 

DECLARE SYS$SETPRN ENTRY (ANY) 3 


All other variables, and the procedure call, would be the same as in Figure 
14-7. 


14.4.3 Using the DESCRIPTOR Built-In Function 


If a parameter descriptor specifies ANY without VALUE, a corresponding 
argument may be a reference to the DESCRIPTOR built-in function. For 
example: 


DECLARE P ENTRY (ANY) 34 


DECLARE (4X+¥) FIXED DECIMAL (7+2)35 
CALL P(DESCRIPTOR(X?)) 5 
CALL PCY¥)s 


Here, X is passed by descriptor because the DESCRIPTOR built-in function 
so specifies. Y is passed by reference. 


Argument Passing 14-11 


OPTIONS (VARIABLE). At least one parameter descriptor must be speci- 
fied; the last parameter descriptor given in the ENTRY attribute is used for 
any extra arguments. 


The Formatted ASCII Output (SYS$FAO) system service is an example of a 
procedure that has a variable-length argument list. It can be declared as 
follows: 


DECLARE SYS#FA0O ENTRY (CHAR(#) + FIXED BINARY(C15); 
CHAR (#)+ ANY VALUE) OPTIONS (VARTABLE) : 


This parameter descriptor specifies only four arguments. When SYS$FAO is 
invoked with more than four arguments, PL/I uses the parameter descriptor of 
the last parameter (ANY VALUE) to pass all the additional arguments. If any 
argument that will be specified is not to be passed by value, you must specify 
a parameter descriptor for the argument in the declaration. | 


14.5.2 Optional Arguments 


In the PL/I language, there can be no optional parameters to a PL/I proce- 
dure. You must always specify a written argument for each parameter in the 
entry declaration. 


Many non-PL/I procedures with fixed-length argument lists accept optional 
arguments and provide a default action if no value or a value of zero is 
specified for the optional argument. When an optional argument is not speci- 
fied, its corresponding argument list longword must contain a zero. 


In PL/I, you can omit the specification of an optional argument in a written 
argument list as long as you enter the correct number of commas to ensure 
that the argument list will have the correct number of longwords. You can 
indicate that you are not specifying an optional argument in either of the 
following ways: 


e Omit the argument from the argument list. 


e If the argument is to be passed by immediate value, specify a zero for the 
written argument. 


For example, an argument list that has three optional arguments can be 
written as follows: 

C49) 

If the parameter descriptor of each argument specifies ANY VALUE, the 
argument list may also be written: 

(04040) 

In either case, the called procedure must detect and interpret zeros in the 


argument list. The following example illustrates optional arguments omitted 
from an argument list: 


DECLARE SYS$ASCTIM ENTRY ¢ 
ANY sCHARC#) ;ANY) OPTIONS (VARTABLE?) + 
TIME-STRING CHARACTER( 24) 3 


+ 


CALL SYSSASCTIM(C+TIME_STRING:s +) $ 
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Chapter 15 
Global Symbols 


In standard PL/I, a variable that is to be shared by external procedures must 
be declared with the EXTERNAL attribute in each procedure that references 
it. VAX-11 PL/I provides an alternate method for defining external variables. 
Using the GLOBALDEF attribute, one module may completely declare an 
external variable; all other modules that reference the variable declare it with 
the GLOBALREF attribute. The VALUE and READONLY attributes pro- 
vide additional control over the storage of these variables. 


Even if a PL/I program does not itself define external variables in this way, 
the GLOBALREF attribute permits a PL/I program to access variables de- 
fined in modules written in other languages. 


This chapter describes: 
e Using global symbols within PL/I procedures 
e The READONLY and VALUE attributes 


¢ Declaring and using system-defined global symbols 


15.1 Using Global Symbols in PL/I Procedures 


Within your PL/I programs, you can define variables as global external sym- 
bols when you are coding calls to system procedures. You can also use global 
symbols instead of external variables in PL/I procedures and functions. 


Table 15-1 summarizes the differences between global symbols and external 
variables. Note that a primary difference between these variables is the man- 
ner in which the linker allocates storage for them. Linker storage allocation is 
described in Chapter 18, “Storage Allocation and Usage.”’ 


e Only one procedure in a program may declare a particular external variable 
with the GLOBALDEF attribute. 


The GLOBALREF attribute indicates that the declared name is a global 
symbol defined in an external procedure. 


The GLOBALREF attribute implies the EXTERNAL and STATIC attrib- 
utes. The corresponding name must be declared in another procedure with the 
GLOBALDEF attribute or, if the external procedure is written in another 
programming language, its equivalent in that language. 


The following restrictions apply to the use of the GLOBALREF attribute: 


e The GLOBALRFEF attribute conflicts with the INITIAL, GLOBALDEF, 
and INTERNAL attributes. 


e If GLOBALREF is specified with the FILE attribute, no other file descrip- 
tion attributes can be specified. 


15.1.2 Defining Global Symbols in PL/I 


To create a global symbol definition in a PL/I program, you must declare it 
with the GLOBALDEF attribute in one, and only one, PL/I external proce- 
dure. The GLOBALDEF attribute implies the EXTERNAL attribute. 


An external variable defined with the GLOBALDEF attribute can be accessed 
by external procedures that declare the name with the GLOBALREF attrib- 
ute. For example, the procedure ABC contains: 
ABC: PROCEDURE: 

DECLARE UNIQUE.VALUE GLOBALDEF FIXED BINARY 


INITIAL (6033 
DECLARE XYZ EXTERNAL ENTRY (CHARACTER (%))5 


CALL XYZ C’STRING‘)5 


The procedure XYZ contains: 


X¥Z: PROCEDURE (STRING_VAL) 3 
DECLARE UNIQUE_YALUE GLOBALREF FIXED BINARY: 


+ 


In the preceding example, the external variable UNIQUE_VALUE is de- 
clared with the GLOBALDFEF attribute and initialized in the procedure ABC. 
The called external procedure XYZ declares this variable with the attribute 
GLOBALREF and the appropriate data type attributes. 


15.1.3 Using MACRO Global Symbols with Multiple Definitions 


Using the VAX-11 MACRO programming language, it is possible to give a 
global external variable more than one name. However, in a PL/I procedure, 
only one global symbol name may be used for a particular variable. PL/I 
assumes that distinct global symbol names denote distinct storage locations; 
the storage associated with different names may not overlap. This rule applies 
only to global symbols that are declared without the VALUE attribute. 
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4, All declarations of the variable must specify the VALUE attribute. 


5. The variable is not addressable; thus it cannot be used as the argument of 
the ADDR built-in function. 


A variable declared with the VALUE attribute can be specified as a value to 
initialize another variable; it must have the same data type as the variable 
that is being initialized. For example: 


DECLARE TEMP GLOBALDEF FIXED VALUE INITIAL(10); 
ABC FIXED STATIC INIT(TEMP) § 


The declaration of ABC in this example gives ABC the value 10. 


15.3 Obtaining Definitions for System Global Symbols 


Within the VAX/VMS system, many global symbol definitions are used and 
accessed by programs and procedures in many ways. The most common uses 
are to define symbolic names for: 


e Return status values from system procedures 

e Function codes for system programs 

e Symbolic names for system mailbox message senders 
e Bit field definitions in system data structures 


From a PL/I program, you can declare the symbolic names for system global 
symbols with the GLOBALREF and VALUE attributes. The format of these 
declarations is: 


DECLARE symbol-name GLOBALREF FIXED BINARY(31) VALUE; 


The GLOBALREF attribute indicates to PL/I that the variable is a reference 
to a global symbol defined in another module. The VALUE attribute indicates 
that the value of the variable is to be treated as if it were a constant. 


The definitions for system global symbols are declared in the default system 
object module libraries. These libraries are automatically searched when you 
link a PL/I program. Of particular interest are the global symbols that define 
symbolic names for system service and file system return status values. Their 
use is described in the next chapter, ‘““Return Status Values.”’ 
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Chapter 16 
Return Status Values 


The VAX-11 mechanism for returning a status value among procedures is to 
return a fixed-point binary value in the general register RO. This value, called 
a return status value, indicates the success or failure of the operation per- 
formed by the called procedure. 


In PL/I, passing a return status value in RO is equivalent to a function return 
of a value declared as FIXED BINARY(31). In fact, when a PL/I function that 
returns a value that can be expressed in 64 bits or less executes a RETURN 
statement, PL/I places the return value specified in RO, and R1 if necessary, 
before returning control to the caller. | 


Thus, to.obtain a return status value from any system procedure, you can 
declare the procedure as a function as shown in the following example: 
DECLARE SYS#SETEF ENTRY (FIXED BINARY(31) VALUE) 

RETURNS (FIXED BINARY (311334 
This declaration of the SYS$SETEF procedure allows you to invoke the pro- 
cedure as a function and to obtain a return status value. 


This chapter provides information on: 


e The format of a return status value, that is, the meaning of particular bits 
within the value 


e Recommended techniques for testing a return status value for success or 
failure or for a specific condition 


The information in this chapter also applies to the return status values sig- 
naled by PL/I run-time procedures. Error signaling and condition handling 
are described in detail in Chapter 17, “Error Signaling and Condition Han- 
dling.”’ 


16.1 Format of Return Status Values 


All VAX/VMS system procedures and programs use a longword value to com- 
municate specific return information. When a main procedure executing un- 
der the control of. the DCL command interpreter executes a RETURN state- 
ment to return control to the command level, the command interpreter uses 
the return status value to display a message on the current output device. 
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module $STSDEF. This module is in the default PL/I text library 
PLISYSDEF.TLB (described in Section 2.4.7, “Default System INCLUDE 
Library’). The module $STSDEF contains the following declarations: 


declare sts#$value fixed binary(31)> /*® status value ¥*/ 
i sts#fields based (addr(stst#ualue)); 

2 sts#severitys /* low-order 3 bits #/ 
BS sts#success biti): /* low-order bit ¥*/ 
3 ststrest bit(2)+ /* Bits i through 2 #/ 

2 sts#msg; /* bits 3 through 15 ¥*/ 
3 sts#msgino bitliZ) + /# numeric value ¥*/ 
3 sts#fac_sp bitlli)s /* if sets facility specific */ 

2 sts#fac» /* bits 16 - 27 ¥/ 
3 sts#facino bittlli)s /*® facility number ¥*/ 
3 ststoustridef bit¢l)s /* © = DIGITAL */ 

2 stst#contral: 
3 sts#inhiblmsg bitlids /* 1 = do not Print ¥/ 
3 sts#reserved bit(3is /* 32 bits */ 

© sts¢filler character(O}3 /* for byte alignment #*/ 


To obtain these declarations, specify a %INCLUDE statement in a PL/I pro- 
gram as follows: 


%ZINCLUDE #STSDEF3 
The compiler will locate this module in PLISYSDEF automatically. 


The next three sections describe the following ways you can use these 
variables: 


e To test for successful or nonsuccessful completion of a procedure 
e To test whether a procedure returned a specific value 
e To determine, set, or display any field within a longword status value 


Remember that you can test return status values from system procedures only 
if you declare the procedures as functions. 


16.2 Testing for Success or Failure 


To test a return status value for success or failure, you need only test the 
variable STS$SUCCESS declared in the structure STS$FIELDS. If this bit is 
true, it indicates that the return value is a successful value. For example: 
DECLARE SYS#SETPRN ENTRY (CHARACTER(*)) 


RETURNS (FIXED BINARY (313035 
“INCLUDE #STSDEF 3: 


STS$VALUE = SYS#SETPRN( ‘Student 5 
IF “STS#SUCCESS THEN GOTO BAD_NAME: 


The statements at the label BAD._-_NAME can test the value of the variable 
STS$VALUE and take some action based on its value. 


16.3 Testing for Specific Return Status Values 


‘Each numeric return status value defined by the system has a symbolic name 
associated with it. The names of these values are defined as system global 
symbols, and their values can be accessed by referring to their symbolic 
names. 
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The next example illustrates the invocation of the Set Event Flag 
(SYS$SETEF) system service, followed by tests for (1) success or failure and 
(2) the successful status code SS$_WASSET. 
DECLARE SS$.WASSET FIXED BINARY GLOBALREF VALUE: 

SYS#SETEF ENTRY (FIXED BINARY(31) VALUED $ 
YINCLUDE $STSDEF 3 
STS#VALUE = SYS$SETEF (4)3 


IF “STS#SUCCESS THEN RETURN (STS#VALUE?) 3 oO 
JTF STS$VALUE = S5$.WASSET THEN DO; @ 


+ 


In this example, the symbolic name SS$_WASSKET is declared as a global 
symbol. The value associated with this return status is a successful value; it 
indicates that the flag specified in the procedure invocation was previously 
set. 


The procedure invocation returns the status value in the variable 
STS$VALUE. The IF statement checks the variable STS$SUCCESS for 
success or failure. If the service returned a failure condition, the procedure 
returns with the value of STS$VALUE in the RETURN statement. If the 
service returned a successful status, the procedure continues with an IF state- 
ment that checks whether the flag was previously set. If so, the DO statement 
specified in the THEN clause activates the DO-group. 


Note the effect of the RETURN statement in this example. If this procedure is 
the main procedure, the RETURN statement that specifies the current value 
of the variable STS$VALUE will cause the command interpreter to display 
the error message associated with this return status value. 


16.4 Setting and Displaying Fields Within a Status Value 


You can use the structure STS$FIELDS to set or display fields within a status 
value. For example, if you wish to define application-specific message num- 
bers using the format used by VAX/VMS, you can specify a facility-wide 
message number, set the STS$CUST_DEF field to ‘1’B, assign unique num- 
bers to messages, and define severities for the messages. 


Since the fields within this structure are defined as bit strings, and it is 
usually more convenient to express facility or message numbers as integers, 
you must use the UNSPEC built-in function to convert integer values to the 
appropriate bit-string representation. The following example shows how to 


Return Status Values 16-5 


Chapter 17 
Error Signaling and Condition Handling 


The standard PL/I language provides error handling and signaling through the 
use of the ON, REVERT, and SIGNAL statements and several built-in 
functions. In VAX-11 PL/I, these statements and the functions they perform 
have been extended to encompass VAX-specific and program- or application- 
specific error signaling and condition handling. This chapter describes: 


e The relationship of the VAX/VMS condition-handling facility to VAX-11 
PL/I’s condition-handling features 


e VAX-11 PL/I extensions for condition handling 
e The actions that an ON-unit can take 


e The search for ON-units when a condition is signaled and the default 
handling performed when no ON-unit exists for a given condition 


All VAX-11 PL/I run-time procedures use PL/I condition handling. The 
information in this chapter supplements the information on ON conditions 
and ON-units in the VAX-11 PL/I Encyclopedic Reference, by providing 
details that are specific to PL/I programs executed under the control of the 
VAX/VMS operating system. 


17.1 Relationship of VAX/VMS Condition Handlers to PL/I ON- 
Units 


In the VAX/VMS environment, an exception condition is a hardware- or 
software-detected condition that synchronously interrupts the execution of an 
image. A condition handler is a procedure that exists specifically to respond to 
one or more such conditions; each procedure in the program can establish a 
condition handler. It is usually the responsibility of each handler to determine 
the specific condition that was signaled, and to decide whether or not to 
handle it. 


Most high-level languages establish condition handlers by calling the VAX-11 
Run-Time Library procedure LIBSESTABLISH. The PL/I language, however, 
has in the ON-unit a condition handler defined to handle a specific condition. 
By using the keyword condition names defined by PL/I and the extensions 
provided by VAX-11 PL/I, you can write ON-units to handle any possible 


17-1 


17.1.2 Values for ON Condition Names 


For any condition that is signaled, the built-in function ONCODKE returns the 
specific 32-bit status value that describes the condition. The low-order three 
bits of this value contain the severity of the condition (success, warning, error, 
and fatal). The severity of a condition is important only when no ON-unit 
exists for a condition, and default condition handling is performed by either 
PL/I or the system (see Section 17.4, “Search for ON-Units’’). 


All VAX/VMS-defined conditions have symbolic names associated with them. 
Table 17-1 lists the PL/I keyword condition names and the global symbol 
names for the VAX/VMS condition values associated with them. If the 
ONCODE built-in function is invoked in an ON-unit for the related PL/I 
condition name, it returns the value of the indicated global symbol. 


Table 17-1: ONCODE Values for PL/I ON Conditions 


PL/I Condition VAX/VMS Global Symbol Name! 


ENDFILE PLI$__ENDFILE 
ENDPAGE PLI$__ENDPAGE 


ERROR A specific status value associated with the error that caused the 
condition to be signaled” 


FINISH PLI$_FINISH 
FIXEDOVERFLOW SS$__DECOVF or SS$_INTOVF 


KEY RMS$__name, where name is one of the following specific RMS 
condition names that describe a key error: RMS$__RNF, 
RMS$_DUP, RMS$_KEY, RMS$_MRN, RMS$_REX; or, 
PLI$__name, where name describes a PL/I run-time error, for 
example PLI$__CNVERR? 


OVERFLOW SS$_FLTOVF 


UNDEFINEDFILE RMS$__name, where name indicates a specific status value 
associated with an RMS error; or, PLI$__name, where name 
describes a PL/I run-time error” 


UNDERFLOW SS$_FLTUND 
VAXCONDITION Any user-defined condition value that was signaled 
ZERODIVIDE SS$_FLTDIV 





1. If a PL/I condition is explicitly specified in a SIGNAL statement, the ONCODE value 
corresponds to the condition message associated with the condition, for example, 
PLI$.__UNDFILE, PLI$__KEY, and so on. 

2. These names correspond to the identification fields in the run-time messages. The RMS 
messages are listed in the VAX-11 Record Management Services Reference Manual. PL/I 
messages are listed in Appendix B of this manual. 
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SIGNAL ARRAY 
fe | 
first signal argument, if any 


additional arguments, 
if 


any 
PC program counter at the time 
the condition occurred 
PSL processor status longword at 
the time the condition occurred 
MECHANISM ARRAY 
of 


: establisher frame 


Figure 17-2: The Argument List Passed to an ON-Unit 














number of arguments in this array 


usually contains the same value as 
that returned by ONCODE 


depend on the condition 


ARGUMENT LIST WHOSE LOCATION 
tS RETURNED BY ONARGSLIST 


ae cs 


pointer to signal array 


pointer to mechanism array 








number of arguments in this array 


copy of the frame pointer of the block 
that established the ON-unit 

depth of block activation of the block 

in which the condition occurred, relative 
to the establisher frame 


contents of Register 0 when the condition 
was Signaled 


contents of Register 1 when the condition 
was signaled 





The text module $;CHFDEF contains PL/I declarations of these structures, as 
shown below: 


declare chft#argptr Pointers 
declare 1 chftarglist based (chft#argptr?) ; 
chft#count fixed binary(3li+ /# always 2 ¥f 

chf#sisgarglst Pointer: 

chf#mcharglst Pointer 
declare 1 chf#sisnal_warray based (chf€sigarglsti: 

chf#sig_largds fixed binary(3li: f/*® ardument count #/ 
chf$sisg_name fixed binary(3l}; f/*® condition name #/ 
chf#sigiarg (chf#sigwlargs-3)} fixed binary {3ii: 

chf#pc fixed binary (3li); 

chf¢#epsl fixed binary(3li: 

hf#mechwarray based (chftmceharglst) + 

chfémchiargs fixed binary(3li):; f# always 4d #/ 
chft#mchuframe fixed binaryiGli: 

chfémchidepth fixed binaryi(3lii: 

chf#mechusaurO fixed binary(3li+ 

chf#mcohuisauri fixed binary(3iis 


This module is in the default PL/I text library PLISYSDEF.TLB. You can 
include this module in a PL/I program by specifying: 


PJ Pa pa 


= 
PIPPI PI Pao Pa Po ha Pa pd 


ZINCLUDE $CHFDEF 5 


The PL/I compiler locates this module in PLISYSDEF.TLB when it compiles 
the source program (see Section 2.4.7, “Default System INCLUDE Library’). 
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17.2 VAX-11 PL/I Condition-Handling Extensions 


VAX-11 PL/I defines two special keywords for the ON statement to provide 
additional flexibility in condition handling: 


¢ The ANYCONDITION keyword lets you establish an ON-unit to trap all 
nonspecific conditions. 


e The VAXCONDITION keyword lets you handle and signal either 
VAX/VMS-specific conditions or application-specific conditions. 


These keywords, and the ways you can use them in your applications, are 
described individually in the next subsections. 


17.2.1 An ANYCONDITION ON-Unit 


An ANYCONDITION ON-unit is, in effect, a “catch-all”? condition handler. 
It is executed whenever a condition for which no ON-unit exists is signaled in 
the current block or any of its descendents. Figure 17-3 illustrates three blocks 
in the calling sequence. Procedure A establishes an ON-unit for FIXED- 

OVERFLOW conditions and procedure B establishes an ANYCONDITION 
ON-unit. If any condition (including the FIXEDOVERFLOW condition) is 
signaled in procedure B after this ON statement is executed, or in procedure 
C, the ANYCONDITION ON-unit in procedure B is given control. 


A: PROCEDURE OPTIONS (MAIN) ; 
ON FIXEDOVERFLOW BEGIN ; 








END : 
CALL B; 


B: PROCEDURE ; 
ON ANYCONDITION BEGIN ; 


END ; 
CALL C; 


C: PROCEDURE ; 


END : 


Figure 17-3: An ANYCONDITION ON-Unit 


Within the VAX/VMS programming environment, the ANYCONDITION 
keyword provides a way to ensure that conditions signaled by PL/I procedures 
are not passed to non-PL/I procedures. This is particularly useful for proce- 
dures that use the VAXCONDITION condition to signal information from 
one block activation to another. 


Note that exiting from an ANYCONDITION ON-unit with a nonlocal GOTO 
requires special coding. This situation is described in Section 17.3.8, 
“Unwind.” 
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When these ON-units are in effect, other procedures can declare and use the 
names SIGNAL_STOP, SIGNAL_FOUND, and SIGNAL_NOTFOUND to 
signal these conditions. For example: 


DECLARE SIGNAL.FOUND GLOBALREF FIXED BINARY: 
SIGNAL VAXCONDITION( SIGNAL FOUND) 3 


Note that in this example, the application-specific values are initialized to the 
integers 9, 17, and 33. In actual practice, these values should be defined using 
the entire 32 bits of a status value, with the appropriate bit set to indicate 
that the value is a customer-defined value. For information on interpreting 
and setting status values, see Chapter 16, ““Return Status Values.” For infor- 
mation on declaring global symbols with the GLOBALDEF attribute, see 
Chapter 15, ““Global Symbols.” 


17.3 Actions That an ON-Unit Can Take 


The possible courses of action an ON-unit can take during its execution as a 
result of a condition are: 


e Handle the condition and return control to the point at which the condition 
was signaled 


e Resignal the condition and request PL/I to locate another ON-unit to han- 
dle it 


e Execute a nonlocal GOTO statement and cause PL/I to unwind the call 
stack 


e Stop the program 


These courses of action are described individually. 


17.3.1 Handle the Condition 


A condition is assumed to be handled in PL/I when the ON-unit established 
for the condition completes executing without performing one of the following 
actions: 


e Executing a nonlocal GOTO 

¢ Calling the RESIGNAL built-in subroutine 
e Signaling another condition 

e Executing a STOP statement 


When the condition is handled, PL/I continues execution of the program at 
the point of interruption. 


17.3.2 Resignal the Condition 


In VAX-11 PL/I, an ON-unit can decide that it does not want to handle a 
condition and request that, rather than returning control to the point of inter- 
ruption, PL/I continue to look for another ON-unit to handle the condition. 
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This removal of call frames from the call stack is called an unwind. Figure 
17-5 illustrates a situation in which an unwind occurs. The circled numbers 
indicate the order of execution. The ERROR ON-unit established in proce- 
dure A receives control when the ERROR condition is signaled in procedure C. 
This ON-unit executes the GOTO PRINT_MSG statement. The label 
PRINT__MSG is in procedure A. Thus, the call stack is unwound and the call 
frames for the ON-unit, procedure C, and procedure B, in that order, are 
removed from the stack, and execution continues at the label PRINT__MSG. 


A: PROCEDURE OPTIONS (MAIN) ; 0 
ON ERROR GOTO PRINT_MSG ; 


4) 










CALL B: 
PRINT._MSG: 


15) 


B: PROCEDURE ; 


2) 


CALL C; 
RETURN : 
END ; 
C: PROCEDURE : 3] ERROR signaled 


RETURN : 
END ; 


pt ee q ERROR ON-unit established by 
procedure A 


Figure 17-5: Unwinding the Call Stack 


When an unwind occurs in the VAX/VMS environment, each call frame in the 
calling sequence is examined to determine if a condition ON-unit exists for 
that frame. If so, the ON-unit is called with the -condition value 
SS$_UNWIND, and the ON-unit has the chance to perform block- or proce- 
dure-specific cleanup operations. 


17.3.4 Stopping the Program 

An ON-unit may specify that the program is to be terminated by executing a 
STOP statement. For example: 

ON UNDEFINEDFILE(INFILE) BEGIN: 


PUT EDIT(¢ ‘File’ ;OQNFILE(};‘undefined. Error’ sONCODE()) 
(Ark sArK Ark sF CLO} D3 

STOP 

END 54 
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If the signal is the ENDPAGE condition, the default PL/I handler exe- 
cutes a PUT PAGE for the file, and then continues the program at the 
point at which ENDPAGE was signaled. 


If the signal is the ERROR condition and the severity is fatal, the 
default handler signals the FINISH condition. Then, one of the follow- 
ing occurs: 


- If a FINISH ON-unit is found, it is given a chance to execute. If it 
executes a nonlocal GOTO or signals another condition, program exe- 
cution continues. 


- If no FINISH ON-unit is found, or if a FINISH ON-unit completes 
execution by handling the condition, then PL/I resignals the condition 
to the default VAX/VMS condition handler. This handler prints a 
message, displays a traceback, and terminates the program. 


If the signal is any condition other than ENDPAGE or ERROR with a 
fatal severity, the default PL/I handler signals the ERROR condition 
with the severity of the original condition. Then, one of the following 
occurs: 


- If an ERROR ON-unit is found, it is executed. If it completes execu- 
tion by handling the condition, the program continues. 


~ If an ERROR ON-unit is not found, the default PL/I handler resignals 
the condition. If this resignal results in control returning to the sys- 
tem, the default VAX/VMS condition handler prints a message and a 
traceback. If the error is a fatal error, the default handler terminates 
the program; if the error is nonfatal, the program continues. 


17.4.2 Default Handling for Non-Main Procedures 


If the call frame at which the procedure was entered did not specify the MAIN 
option, the default condition handling is as follows: 


PL/I searches for specific ON-units in the following order: 


‘e 


Oe 


3. 


A VAXCONDITION ON-unit established for the specific condition 
value that is being signaled 


A PL/I ON-unit established for a PL/I condition name, if PL/I defines a 
name for the condition 


An ANYCONDITION ON-unit 


If one of these ON-units exists, it is executed and the search is ended. If 
the ON-unit completes execution by handling the condition, the program 


continues at the point at which the condition was signaled. 


If no ON-units are found in any call frame, the condition is resignaled to 


the caller. If the resignal results in return of control to the system, the 
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Figure 17-7 illustrates the search sequence when a second condition occurs 
during the execution of an ON-unit. The circled numbers indicate the order of 
execution. The ERROR condition in procedure C is handled by the ON-unit 
established in procedure B. During the execution of this ON-unit, a 
FIXEDOVERFLOW condition is signaled. PL/I locates the ON-unit estab- 
lished for FIXEDOVERFLOW conditions in procedure C and gives it control. 


A: PROCEDURE OPTIONS (MAIN) ; 







CALL B; 


B: PROCEDURE : 2] 
ON ERROR BEGIN ; 


4) 


Original 
ERROR 
signaled 


C: PROCEDURE ; 
ON FIXEDOVERFLOW BEGIN; 


END ; 


5] 


Gre rae tay ge ERROR ON-unit established 
by Procedure B 


“ signaled 
in ERROR 


ON-unit 


Bayete 6) 


| 
| 
| FIXEDOVERFLOW 
| 
| 


Figure 17-7: Effect of Multiple Conditions 


Note that if the second condition is the same condition as the first, and the 
ON-unit does not establish another ON-unit, the same ON-unit will be exe- 
cuted repeatedly as the condition is signaled. A similar situtation results when 
a STOP statement is executed within a FINISH or ANYCONDITION 
ON-unit — that is, the program will enter an interminable loop when the 
STOP statement executes. The STOP statement signals FINISH, the current 
ON-unit is reexecuted, the STOP statement is executed again, and so on. 


In a PL/I program, an ANYCONDITION ON-unit or a VAXCONDITION 
ON-unit established specifically to handle the SS$_UNWIND condition is 
invoked during the unwind. The following example illustrates a 
VAXCONDITION ON-unit: . 
DECLARE SS$ UNWIND GLOBALREF VALUE FIXED BINARY(31)3 
ON YAXCONDITION(SS$_UNWIND) BEGINS 

CLOSE FILE(DATA_REC_TEMP) ENVIRONMENT ¢ 

DELETE(NO) 33 
END} 


When an ON-unit that is handling the unwind condition completes execution, 
the unwind continues. 
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Part IV 
Programming Considerations and Examples 


Chapter 18 
Storage Allocation and Usage 


This chapter provides some general information on: 
e How the compiler and linker use program sections 


e How to allocate storage within an area 


18.1 Program Sections 


When the PL/I compiler creates an object module, it groups data in the object 
module into contiguous areas called program sections. The grouping is 
performed on the basis of the attributes of the data — for example, whether it 
contains executable code or read/write variables. 


The compiler also writes, into each object module, information about the 
program sections contained in it. The linker uses this information when it 
binds object modules into an executable image. As the linker performs its task 
of allocating virtual memory for the image, it groups together program 
sections that have similar attributes. 


18.1.1 Attributes of Program Sections 


Table 18-1 lists the attributes that can be applied to program sections. The 
first column lists pairs of conflicting attributes. 
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Table 18-2: Program Sections for PL/I Variables 


Storage Program Program 
Class Section Section 
Attributes Name! Attributes 


EXTERNAL STATIC ” PIC, OVR, REL, GBL, SHR, 
NOEXE, RD, WRT 


EXTERNAL READONLY PIC, OVR, REL, GBL, SHR, 
NOEXE, RD, NOWRT 


INTERNAL STATIC $DATA PIC, CON, REL, LCL, NOSHR, 
NOEXE, RD, WRT 


INTERNAL READONLY $CODE PIC, CON, REL, LCL, SHR, EXE, 
RD, NOWRT 


GLOBALDEF $DATA PIC, CON, REL, GBL, SHR, 
NOEXE, RD, WRT 


GLOBALDEF (psect-name) psect-name PIC, CON, REL, GBL, SHR, 
NOEXE, RD, WRT 


GLOBALDEF READONLY $CODE or PIC, CON, REL, GBL, SHR, 
psect-name NOEXE, RD, NOWRT 








1. name is the identifier of the variable declared with the specified attribute. psect-name is the 
name specified in the definition of the global symbol. 

2. File constants have the same attributes as EXTERNAL STATIC variables, but with the 
NOSHR attribute instead of the SHR attribute. 


18.1.3. Sharing Program Sections with FORTRAN Procedures 


In a FORTRAN program, separately compiled procedures share data by 
declaring COMMON sections and specifying the names of one or more varia- 
bles to be placed in those sections. Each named COMMON represents a 
separate program section; each procedure that declares the COMMON with 
the same name can access the same variable. 


A PL/I external variable called name therefore corresponds to a FORTRAN 
COMMON with the same name. The examples below illustrate PL/I proce- 
dures and FORTRAN procedures that share data. 


STRING.PLI contains: 
STRING: PROCEDURE OPTIONS (MAIN) 3 


DECLARE KY2Z EXTERNAL CHARACTER(2ZO) ; 
PRSTRING ENTRY 5 
XYZ = ‘THIS 15 A STRING’S 
CALL PRSTRINGS 

STOP $ 

END 5 
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18.2 Allocation of Storage in an Area 


VAX-11 PL/I supports the AREA and OFFSET data type attributes, but does 
not provide support for allocation of storage for variables within the area. 
There are a variety of techniques that can provide management of space 
within an area; the algorithm to use for a particular application depends on 
the application’s requirements. 


This section presents an algorithm for storage management in an area that 
illustrates some of the considerations involved. It describes three procedures 
that allocate and free space within an area: 


e INITIALIZE_AREA initializes an area of a given size. The area size must 
be a multiple of eight bytes. 


e ALLOCATE_IN__AREA determines whether there is sufficient free space 
within the area for a given variable. If so, it returns an offset to the allocated 
space. If not, it returns a null offset value. 


e FREE_AREA reclaims free space when a given variable is deallocated from 
an area. 


Figures 18-1 through 18-3 illustrate calls to these procedures and the resulting 
area and space allocation following each call. The procedures and the algor- 
ithms used by each are described in Sample Program 18-1, which follows the 
figures. 


QECLARE RAPE TLE AREAS TS? : 


TRITIALTSE.AREA ENTRY 






CALL INITIALTZE.AREA (MAPFILE? $ 


0 must be zero @ 
4 


next free block pointer 


ra © 
12 


size of this free block 
504 


| re 


1. The first longword of an area must be zero. This longword is reserved to DIGITAL. 


@ , 


2. The second longword points to the beginning of the free list. that is. a chain of free blocks 
within the area. When this procedure initializes an area, it sets this free list pointer to point 
to the next longword in the block. 


3. Each free block header has the format: 
DECLARE 1 FREEBLK BASED, 
2 NEXT OFFSET (TARGET__AREA), 
2 SIZE FIXED BINARY(31): 2 
When the area is initialized. the NEXT field of the first free block header is set to a null 
offset value and the SIZE field is set to the size of the area. minus the eight bytes required 
for the reserved first longword and the free list pointer. 


Figure 18-1: Initializing an Area 
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DECLARE FREE.IN AREA ENTRY (FIXED BINARY(31)> OFFSET: AREAC#I)5 


CALL FREELWINOAREA (100; FILEOFF¢2)+ MAPFILE? 3 


O must be zero 









4 free list pointer 


8 next free block pointer @ 


a 


12 
size of this free block 
16 


Remaining free space 
in this block 


288 
Allocation for request 
of 40 bytes 


328 
next free block pointer 


size of this free block 









432 


iv, 


SS 





\7 
4 
se 
om 
S 
OOO 
SSK 
SOK SON 
KKK 


os 
OS 
SX 


© 
‘> 
SOX 
SO 








0. 
% 
SOO 
SOS 
om 


Allocation for request BS Allocated space 


of 80 bytes [| 
Free space 


1. FREE__IN__AREA updates the NEXT field of the first free block header to point to the 
freed space. 






o's% 
SSO 


e 


oe 


VAX 7 
see: 
SSS 
SSK 
SSeS 


DS 








vO 


\/ 
oO 


2 
‘s 
NS 
‘S 
SSS 
bs 





2. The first two longwords of the freed space are written with a free block header. The NEXT 
field is set to zero (since there are no more free blocks), and the SIZE field is set to indicate 
the number of bytes in the block. 


Figure 18-3: Freeing Space Within an Area 
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Sample Program 18-1: Storage Management Within an Area 


i& 
This module controls allocation within an area, 


There are three entry Points: 


ALLOCATE_IN_AREA - allocate sPace within an area 
INITIALIZE_AREA - initialize area for storage allocation 
FREELIN AREA - free storage Within an area 
*/ 1] 
ALLOCATE_INUAREA: PROCEDURE(REQUEST_SIZE,REQUEST_AREA) RETURNS( OFFSET) $ 
/* 
Parameters 
*/ 


DECLARE REQUEST_SIZE FIXED BINARY(31)+ /* request size in bytes */ @ 


1 REQUEST AREA: 


2 AREALSIZE FIXED BINARY(15),»5 /* descriptor size field */ 
2 FILLER FIXED BINARY(15); /* unused filler word */ 
2 AREA_POINTER POINTER, /* address of the area ¥/ 
TARGET_AREA AREA(AREA_SIZE) BASED(AREA_POINTER) 5 
/* 
data structures within the input area © 
*/ 
DECLARE 1 AREA_HEADER BASED(AREA_POINTER) +» 
2 RESERVED FIXED BINARY(31), /* reserved to DIGITAL ¥*/ 
2 FREE.LIST OFFSET(TARGET_AREA) » /* offset to first free block */ 
2 LOWLLIMIT FIXED BINARY( 31); /* lowest entry ¥*/ 
1 FREEBLK BASED, /* free block entry ¥*/ 
2 NEXT OFFSET(TARGET_AREA) + /* offset to next entry */ 4 
2 SIZE FIXED BINARY (31)35 /* size of entry #/ 
/* 
local variables 
*/ ; e 
DECLARE NEXT_OFFSET OFFSET(TARGET_AREA) + 


NEXT_OFFSET_VALUE FIXED BINARY(31) DEFINED(NEXT OFFSET) » 


FREE_OFFSET OFFSET» 
FREE.OFFSET_VALUE FIXED BIN(31) DEFINED(FREE_OFFSET) + 


TEMP_OFFSET OFFSETCTARGET_AREA) + /* temporary offset variable */ 
TEMPLOFFSET_VALUE FIXED BIN(31) DEFINED¢TEMP_OFFSET) + 


PREYVIOUS_OFFSET OFFSET(TARGET_AREA) » ; 
PREVIOQUS_OFFSET VALUE FIXED BIN(31) DEFINED(PREVIOUS_OFFSET) § 


(Continued on page 18-11) 
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Sample Program 18-1 (Cont.): Storage Management Within an Area 


/* 


*/ 


/ 


/* 


*/ 


allocate storage in target—area 


Find first free block that is large enough to contain the reauested 
allocation. Stop at the end of the list -- no space for allocation, 


PREVIOUS_OFFSET = OFFSET(ADDR(FREE_LIST) +» TARGET AREA) § 
DO NEXT_OFFSET = FREE_LIST 6) 
REPEAT (NEXT_OFFSET - :FREEBLK. NEXT) 
WHILE (NEXT_OFFSET-?FREEBLK.SIZE < ROUND(REQUEST_SIZE))3 
IF NEXT_OFFSET-?FREEBLK.«NEXT = NULL() THEN 
RETURN(NULL())$ /* no space to allocate */ @ 
PREVIOQUS_OFFSET = NEXT_OFFSET3 
END 3} 


Change free block header to reflect the allocation. 
If the allocation reaunires the entire block» remove the header 
from the free list. 


Return offset of allocated space at end of this free block, 


NEXT_OFFSET->FREEBLK,.SIZE = 
NEXT_OFFSET-=FREEBLK.SIZE - ROUND(REQUEST_SIZE)3 @© 
IF NEXT_OFFSET-=FREEBLK.SIZE = 0 THEN 
PREVIQUS_OFFSET->FREEBLK.NEXT = © 
NEXTUOFFSET-=FREEBLK.NEAT 5 
NEXT_OFFSET_VALUE = NEXT_OFFSET_VALUE + NEXT_OFFSET-?FREEBLK.SIZE3 @ 
RETURN(NEXT OFFSET) 3 


Initialize area header 


INITIALIZE_AREA: ENTRY (REQUEST_AREA) 3 


AREA_HEADER. RESERVED = 03 /* DIGITAL’s longword must be zero */ @® 
FREE_LIST = OFFSETCADDR(LOW ULIMIT) »>TARGET_AREA) 5 
FREE_LIST-2:FREEBLK.NEXT = NULL()3 
FREELLIST-2FREEBLK.SIZE = 
REQSUEST_AREA.AREA_SIZE - 83 
RETURNS 


(Continued on page 18-13) 
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Sample Program 18-1 (Cont.): Storage Management Within an Area 


i* 
Free an allocated block of storage in area 
*/ 


FREE_IN_AREA: ENTRY(REQUEST_SIZE »FREE_OFFSET +REQUEST_AREA)} @ 


/* 
Search the free list to find the place to insert the freed Block, 
*/ 
PREYIOUS_OFFSET = OFFSETC(CADDR(FREE_LIST) +»TARGET_AREA) 5 
DO TEMP_OFFSET = FREE_LIST 
REPEAT (TEMP_OFFSET->}FREEBLK.NEXT) ® 
WHILE ((FREE_OFFSET_VALUE <= PREVIOQUS_OFFSET_UVALUE 
FREE_OFFSET_VALUE = TEMP_OFFSET_VALUE) & 
TEMP_LOFFSET “= NULL ())3 
PREVIOQUS_OFFSET = TEMP_OFFSET: @ 
END 5 
PREVIOUS. OFFSET-?FREEBLK.NEXT = FREE_OQFFSET: 
NEXTUOFFSET = FREE_LOFFSET3$ 
NEXTUOFFSET-:FREEBLK.NEXKT 
NEXTUOFFSET-:FREEBLK.SIZE 


TEMP_OFFSETs 
ROUND(REQUEST_SIZE) 3 


Combine any adJvJacent free blocks into a single free block. 
*/ 
TEMP_OFFSET = FREE_LIST3 16) 
DO WHILE¢TEMP_OFFSET “= NULL())5 
NEXTUWOFFSETUVALUE = TEMP_OFFSET_VALUE + TEMP_LOFFSET-?FREEBLK.SIZE3 
IF NEXT_OFFSET = TEMP_OFFSET-?FREEBLK«NEXT THEN DO3$ 
TEMP_OFFSET-:FREEBLK,.SIZE = 
TEMPLOFFSET-:FREEBLK.SIZE + NEXT_OFFSET-:FREEBLK.SIZE3 
TEMP_OFFSET-=FREEBLK.NEXT = NEXT_UOFFSET->FREEBLK.NEXT$ 
END 35 
ELSE 
TEMPLOFFSET = TEMP_LOFFSET-=:FREEBLK.NEXRT S$ 
END 5 


RETURNS 
/* 

Subroutine to round the request sizes to 8 byte units 
*/ 
ROUND: PROCEDURE(CINPUT_SIZE) RETURNS(FIXED BIN(313)3 @ 
DECLARE (CINPUT_USIZE;1) FIXED BINARY(31)3: 

IT = MOD(CINPUT_SIZE+8) 3 

IF I “= © THEN I = 8 - 13 

RETURN(CINPUT_SIZE + 1)3 


END ROUND: 


END ALLOCATE_IN_AREAS 
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Chapter 19 
System Services 


System services are procedures implemented by the VAX/VMS operating 
system. Although the use of some system services is restricted by privilege 
requirements, many services are available for general programming use. 
System services are described in detail in the VAX/VMS System Services 
Reference Manual. 


This chapter provides information on: 

¢ Declaring system services in PL/I 

e Specifying arguments for system services 

e Testing status values returned from system services 


The last section of this chapter provides examples of calling system services 
from PL/I programs. 


19.1 Declaring System Services 


The default PL/I text library PLISYSDEF.TLB contains declarations for all 
system services as external entries. The text module names have the form: 


SYS$name 


where SYS$name is the name of the system service. Thus, to include the 
declaration of a system service you are going to use, you specify a “cCINCLUDE 
statement as in this example: . 


ZINCLUBDE SYS#TRNLOG? 


The compiler, by default, locates the module SYS$TRNLOG in 
PLISYSDEF.TLB during its compilation. 


Global symbol definitions for the entry vectors of all system services are 
located in the default system object module library, STARLET.OLB in 
SYS$LIBRARY. When you link a PL/I program, the linker searches this 
library by default. 
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Table 19-1: Input Arguments for System Services 


Parameter Declaration 
in PLISYSDEF 


FIXED BINARY(31) 


Argument Data Type 


Numeric values: 
Indicator 
Channel number 
Event flag 
Access mode 
Binary mask 
Buffer size 
Process identification 
UIC 


Character strings: 
Logical name 
Process name 
Device name 
Cluster name 
Time string 


Bit masks: 
32 bits or less 
64 bits 


Time values 
Entry mask or routine 


Buffers: 
Item list 
Quota list 


AST parameter 


Two-longword array 





Program 
Reference 


19-6 
19-6,19-9 


CHARACTER(*) 


BIT(32) ALIGNED 
BIT(64) ALIGNED 


BIT(64) ALIGNED 
EXTERNAL ENTRY 
ANY 


ANY VALUE 
(2) FIXED BINARY(31) 


Table 19-2: Output Arguments for System Services 


Argument Data Type 


Numeric values: 
String length 
Channel number 
Access mode 
Table number 
Process identification 


Character strings: 
Equivalence name 
Time string 


Buffers: 
I/O status block 


Time value 


Two-longword array 
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Parameter Declaration 
in PLISYSDEF 


FIXED BINARY(15) 
FIXED BINARY(15) 
FIXED BINARY(7) 
FIXED BINARY(7) 
FIXED BINARY(31) 


CHARACTER(*) 


ANY 


BIT(64) ALIGNED 
(2) FIXED BINARY(31) 
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For symbolic names that are not defined as VAX/VMS global symbols, 
VAX-11 PL/I provides text modules in the default INCLUDE library 
PLISYSDEF. All symbolic definitions in these modules are defined using 
CoREPLACE statements. Thus, they are treated as constant identifiers rather 
than as variable references. 


The names of the text modules, and the names and values of the symbols 
defined in each, are the same as the MACRO definitions in the system macro 
library, STARLET.MLB. 


The modules required for any system service are included within the text 
module declaration for that service. For example, arguments to the Create 
Process (SYS$CREPRC) system service require symbolic names defined in 
the modules $PRVDEF and $PQLDEF. The module SYS$CREPRC in 
PLISYSDEF contains: 


“INCLUDE @POQLDEF 3 f* auata list definitiscns #/ 
*INCLUDE $PRUDEF 5 /* Privilege bit definitions #*/ 


Table 19-3 summarizes the symbolic definition text modules in PLISYSDEF 
and gives the names of the modules in which they are included. 


Table 19-3: Symbolic Definition Modules in PLISYSDEF 


$ACCDEF SYS$SNDACC 

$JBCMSGDEF } SYS$SNDACC, SYSSSNDSMB 
$J PIDEF SYS§GETJPI 

$0PCDEF SYS$SNDOPR 


$PQLDEF SYS$CREPRC 

$PRVDEF SYS$CREPRC, SYS$SETPRV 

$PSLDEF n/a 

$SECDEF SYS$CRMPSC, SYS$MGBLSC, SYS$DGBLSC 
$SMRDEF SYS$SNDSMB 
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19.4 Examples of System Services 


The examples on the next few pages illustrate a number of system service 
calls. These examples illustrate: 


e Translating a logical name 

e Creating and deleting a mailbox 

e Using timer and time conversion routines 
e A CTRL/C routine 


e Obtaining status and performance information about the current job or 
process 


All the sample programs use the system service INCLUDE files in 
PLISYSDEF to declare the system services. The text of each sample program 
shows the INCLUDE file for the system service. 


All procedures also include the module $STSDEF; however, the contents of 
this text module are not shown in the examples. The contents of $STSDEF 
are listed in this manual in Chapter 16, “Return Status Values.” 
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Sample Program 19-1: Translating a Logical Name 


ORION: PROCEDURE RETURNS(FIXED BINARY (31305 


RINCLUDE SYS#TRNLOGs 
f*% Translate Logical Name system service ¥*/ 
declare sys#trnlog external entry ¢ 

char(*) + f 

fixed bintiS5), 

ehar(#) + 

fixed bin(€7)+ 

fixed bint?) + 

fixed bin(3l) value} 


logical name string #/ 

Variable to receive translated length #/ 
Variable ta receive translated name #/ 
Variable to receive table number #/ 
Variable to receive aceess mode #/ 

table search disable mask #/ 


x * a * * 


oFtions(variable} returns(fixed bin(3iiis 
“INCLUDE #STSDEF 3 


DECLARE CYGDES CHARACTER(G) STATIC INITIAL ( ‘CYGNUS ’): 


NAMEDES CHARACTER( 63) » 2) 
NAMELEN FIXED BINARY(13)5 


DECLARE SS#.NOTRAN GLOBALREF FIXED BINARY(31) VALUE} © 


STS$VALUE = SYS$TRNLOG(CYGDES +NAMELEN NAMEDES:++++)3 @ 
IF STS#VALUE = SSS NOTRAN THEN 

PUT SKIP LIST( ‘CYGNUS not defined’)? @ 
ELSE 

IF sTsssuccess THEN @O 
PLT LIST¢ CYGNUS is?: 
SUBSTR(NAMEDES +1 +NAMELEN))3 

RETURN(STS$VALUE)} @ | 
END 3 
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Sample Program 19-2: Creating a Mailbox 


CREATE MAILBOX: 


*INCLUDE SYS#CREMBS 5 


/*® Create Mailbox and Assign 


declare sys$crembx external entry 


fixed biné3id value 
fixed bin(1iS)+ 
fixed bin(3i)} value 
fixed bin(3l) value 
bitté32) aligned val 
fixed bin(3l) value 
ehart#)) 


+ 


$ 
t 
Wwe + 


? 


f% 
i* 
/* 
f* 
/* 
f# 


PROCEDURE OPTIONS(MAIN) 


( 


RETURNS 
(FIXED BINARY (31))35 


Channel system 


service ¥*/ 


Permanent flag #/ 
YVariable to receive 


maxim 
buffe 


Protection 


acces 


mailbox logical 


‘itt 
Tt 


S 


message 


size #/ 


mask */ 


mode #/ 


oPtiansi{variable) returnstfixed binéS3ilida 
“INCLUDE #STSDEF 3 
ZREPLACE MESSAGE_SIZE BY 13 


8 


a. 4 


channel number #*/ 


Slze #/ 


name #/ 


DECLARE PERMANENT FIXED BINARY(31) STATIC INITIAL (1)+ @ 
CHANNEL FIXED BINARY(15): 
MAX LENGTH FIXED BINARY(31) STATIC INITIAL(MESSAGE.SIZE); & 
PROT.MASK BIT(i16) ALIGNED STATIC INITIAL(‘FFOO’B4)+ @ 
MAILBOX NAME STATIC CHARACTER (1 
INITIAL *PLILMAILBOX?13 


‘* Call & 
5 


i* 


#f 


YS$CREMBX omitting 
TSSVALUE = SYS$CRE 


Feturn to command level 


oPtional 


MBE ¢ 


with 


1) 


PERMANENT : 
CHANNEL + 


MAX LENGTH : 


*+PROTUMASEKE:: ; 
MAILBOXRONAME) 3 


status. 


with an error: the aPrProrriate 


lewel, 


RETURN(STS#VALLUIE) } 
END $ 


messgagd 


If 
& 


i 


arduments. #/ 


bs) 


S7S¢CREMBX 


disPplaved 


completed 


at 


the cammand 
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Sample Program 19-3: Deleting the Mailbox 


DELETE.MAILBOX: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY(31))5 


ZINCLUDE SYS#ASSIGN: 1) 
/* Assign 1/0 Channel system service */ 
declare sys#assign external eantry ¢ 


char(#) + /* device name or logical name */ 

fixed bin(15), 7/* Variable to receive charnel number #*/ 
fixed bin(31l) values /* access mode *¥/ 

char(*)) /* associated mailbox name ¥*/ 


opPtions(variable) returns(fixed binaryvyé3iids 


A’AINCLUDE SYS#DELMBX 3 
/* Delete Mailbox system service #*/ 
declare sys#delmbx external entry ¢ 
! fixed bin(3i1) value) /* channel number of mailbox #/ 


returns (fixed bint3il)a54 
DECLARE MAILBOX NAME CHARACTER(113 STATIC INITIAL 
(*PLILMAILBOX ‘3; 
CHANNEL FIRED BINARY C15) 3 


*INCLUDE $5TSDEF 5 





Rall SYS#ASSIGN and check return: if not suecesaful exit 
STS#VAlLve = SYS#ASSIGN( MAILBOX ONAMNE -CHANNEL: +314 
IF “STS#SUCCE H GOTO EXITOWITHUSTATUS 3 2) 
Call S*YS#DELMBR and check return 


STS$VALUE = SYS$DELMBX(CHANNEL)$ © 


EXITOWITHOUSTATUS: 
RETURN GSTSSVALUE? 5 
END s 
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Sample Program 19-4: Obtaining a System Time Value 


This Procedure converts a time given in ASCII format to a 
Gd-~bit time value that is used internally by YVARSUMS. 
Tneut strings must be of the farms: 

hhimmses.ce (for an a te date or time} 
B- 0c (for a delta time) 






did timin~ ¥ ¥ ¥ ¥ 
dddd hha 





- FZ 


GBETBINTIMs PROCEDURE (ASCITIISTRING? RETURNS(BIT(G4) ALIGNED?) § 


RZINCLUBDE SYS#RINTIMS 
f# Tonvert ASCII String to Binary Time sryetem service #/ 
declare sthintim external entry ¢ 1) 
chart#}¢ f#® ASC 
bhitiGai alisaned) i. ri 






on 


string #/ 


Ts 


mB oo 


I 
able to receive system time #/ 


returns (fixed binary(3idd4 


ZINCLUDE #STSDEF 3 





DECLARE ASCIILSTRING CHARACTER(#) ; 
BINARY.TIME BIT(G4) ALIGNED S 


STS€VALUE = SYS@RINTIMN¢CASCIILSTRING:+:BINARY.TIME} +? @ 





Tf suec fuls return binary time to Foint of invocation: Otherwise : 


return O -~ this results in absolute time 1?Y-NOU-~TLE 









STSsSuce 


ee ie 5S THEN RETURN(BINARYTIME) 3 
~SE RETURN(O) 


EME § 
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Sample Program 19-5: Setting a Timer 


SET.WTIMER: PROCEDURE OPTIONS(MAIN}) RETURNS 
(FIXED BINARY (31375 


ZINCLUBDE SYS#CLREF 3 
/*® Clear Event Flag system service #/ 
declare sys#clref external entry ¢ 
fixed bin(3Sil) valued /* event flag number */ 


returns (fixed bin(@3it)33 
AZINCLUDE SYS#SETIMR: 


/* Get Timer system service #/ 
declare sys#setimr external entry ¢{ 


fixed bin(31l)} value, /* event flag number #/ 
bit(G4) aligned: /*® time value #*/ 

entry values f*® external AST Procedure #/ 
fixed bin(31) value) f* AST Parameter #/ 


oOPtions(variable) returns(fixed biné3tii3 
“’INCLUDE SYS#WAITFRs 
f* Wait for Event Flag System S2@ruice #/ 
declare sys#waitfr external entry ¢ 

fixed bin(S3il) value /* event flags #/ 


returns (fixed biné(Silida 


“INCLUDE $STSDEF 3 
BECLARE GETBINTIM ENTRY ¢ 
CHAR (#)) /# character string time */ @ 
RETURNS (BIT(‘64:) ALIGNED: 3 


/* Clear eavent flag 5 #/ 
STS#VALUE = SYS#$CLRFEF(CR} 3 @ 
IF “STS#SUCCESS THEN RETURN(STS#UALUE) 3 


/* Set the timer for 19 seconds #/ 
STS#VALUE = SYS#SETIMR(S;+:GETBINTIMNG (0 OO2:00:10%3 +235 © 
IF “STS#SUCCESS THEN RETURN(STS#VALUE? 3 
f® Wait for event flag 5 #/ 
STS$VALUE = SYS#WAITFR(S) 3 
TF “STS#SUCCESS THEN RETURN (STS#VALUE} 3 4) 
PUT SKIP LIST( ‘Timer uel’ 


RETURN GLa 
END 


System Services 19-17 


Sample Program 19-6: Establishing a CTRL/C Routine 


SET_-CTRLC: PROCEDURE RETURNS(FIKED BINARY (31))34 


INCLUDE SYSSASSIGN3 1) 
/* Assign I/O Channel system service #/ 
declare sys#assign external entry ¢ 


char(#)+ /* device name or logical name #*/ 

fixed bin(iS), /*® variable to receive channel number */ 
fixed binf(3l1) values /*® access mode ¥*/ 

char(é#)) f* asSociated mailbox name */ 


oFtions(variable) returns(fixed binary (313334 
* INCLUDE SYS#QIG5 
f* Queue T/0 Reauest system service #*/ 
declare sys#qio0 external entry ¢ 


fixed biné3il) values /#® event flag number #*/ 
fixed bin(3il) values /* channel number #/ 

fixed bin(3i} value; f* T/0 funstion code #/ 
avy + '# T/O status block #/ 


x 
entry values f*% external AST Frocedure #/ 
any value) * AST FParameter and I/O Parameters #/ 
oFtiaons(variable} returns (fixed bin(3i)34 
ZINCLUDE SYS#HWAITFR: 
f*% Wait for Event Flas system service #/ 
declare svs#waitfr external entry { 
fixed bint31) value) f* event flag #/ 


Teturns (fixed bin(€S3ijii: 
“%INCLUBE #STSDEF 3 


Declare input and output arguments. The CLINTERFUPT variable is an 
arbitrary value specified for the VAXCONDITION condition 
DECLARE TTCHAN FIXED BINARY(1TS:; f*% terminal channel #¢ @ 
(lO _ SETMODE : 1TO#M_LCTRLCAST: f* I/O function eodes #/ © 
FIXER BINARY( 31) GLOBALFEF VALUE: 


(Continued on page 19-21) 
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Sample Program 19-6 (Cont.): Establishing a CTRL/C Routine 


DECLARE 1 IOSB: 
WALUE FIXED (15): (# Return status #/ @ 
2 HOTOJUSED( 3) FIREDC IS) + 
TOAST ENTRY (POINTER: CTRL/C AST routine #/ & 
AST parameter */ @ 








C.IMTERRUPT FIXED BINARY! 313 ¢ 
EXTERNAL STATIC INIT(S55) 5 


CECLARE IQ.SUCCESS BIT(1) ALIGNED BASED(ADDR(INSB.VSLUE})4 @ 
f* Call Assign 1/0 channel to get a terminal channel and then #/ 
f*® call Queue I/O Reauest to enable the terminal for CTRLYC a; 


STS#VALUE = SYS#ASSIGN (/TT’+TTCHAN: +35 & 
IF “STS#SUCCESS THEN RETURANCSTS$UALUE) 3 


STS#USALUE = SYS#O1I0 (¢1;:TTCHAN: 
LOS. SE TMOBDE+TO#M CTRLOAST:+/# funetion #/ © 
IOSB: f*® T/O status block #/ 
of f*® omit QIO AST argument #/ 
CUWUAST + f# AST routine for ITO8 .CTRLCAST */ 
ADDR CCLINTERRUPT)+/2 paraneter for CTRL/C AST #*/ 
pegadd f# unspecified Pa and ed #/ 

IF “STS#SUCCESS THEN RETURN(STS#YALUE) § 


STSS$VALUE = SYS#HAITFR( 135 
IF “IO.SUCCESS THEN RETURN(IOSB.VALUE}3 @ 
RETURN 135 


EMD 4 
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19.4.4.3 Testing the CTRL/C Routine — The procedure TESTC, in Sample 
Program 19-8, tests the SET_.CTRLC and C__AST routines. The techniques 
used in this procedure can be applied to any procedure in which you want to 
detect and respond to an external interrupt via (RUC). The following notes are 
keyed to Sample Program 19-8: 


1, 


The procedure declares the external routine SET_-CTRLC and the exter- 
nal variable C_INTERRUPT. 


The value of C_INTERRUPT is used as a condition value for the 
VAXCONDITION keyword. This ON statement establishes an ON-unit 
to receive control when any procedure uses the VAXCONDITION key- 
word to signal the condition value C_INTERRUPT. In this short test 
example, the ON-unit merely displays a message, resets the CTRL/C 
handler, and continues the program. In effect, a CTRL/C handler can be 
much more elaborate: you may want to use it to close files, to advance 
processing to a labeled statement or block, and so on. 


Note that once a CTRL/C handler has executed, it cannot be executed 
again unless the I/O request that establishes a handler is reexecuted. To 
keep a CTRL/C handler active, it is common practice to reenable the 
CTRL/C routine within the AST routine itself. In this example, the. 
ON-unit reenables the CTRL/C handler by calling SET__CTRLC. 


The procedure calls SET__CTRLC to establish the CTRL/C handler. 


This procedure places itself in a loop. Each time is entered, it 
displays its message for the C_INTERRUPT ON-unit and continues. 


Note that when this program is run, it can be interrupted at the terminal and 
stopped only by the function. 


Sample Program 19-8: Testing the CTRL/C Routine 


TESTC:s PROCEDURE OPTIONS( MAIN? RETURNS(FIXED BINi( Si): 


SINCLUDE #STSDEF 3 
DECLARE SET_CTRLC ENTRY RETURNS(FIXED BIN( 313); 


ON 


C_LINTERRUPT FIXED BINARY EXTERNAL STATIC INIT(S55)3 @ 
VAXCONDITION(C_LINTERRUPT) BEGIN: @ 
PUT SKIP LIST(/’CTRL/C interrupt ‘)3 
STS#VALUE = SETLCTRLE() 3 
END: 


STS$VALUE = SET.CTRLC()} © 
IF “STS#SUCCESS THEN RETURN(STS#VALUE) 5 


DO WHILE (i225 


END 5 4) 


END: 
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Sample Program 19-9: TIMRE and TIMRB 


TIME: PROCEDURE § 


“%ZINCLUDE SYS#GETJPI 5 
/* Get Job/Process Information system service ¥*/ 
declare sys#getJpi external entry ( 


fixed bin(31) value, 7* event flag number ¥*/ 
fixed bin(3l); /* Process identification ¥*/ 
char(*) +s /* Process mame string */ 
anys /* item list */@ 

ary + /* I/O status block */ 

entry values /* external AST Procedure */ 
any value) /* AST Procedure argument */ 


oPtions (variable) returns (fixed bin(3l))35 
/* INCLUDE file for definitions required by SYS$GETJPI */ 
“include $JPIDEF3 /* item codes */@ 
“ZINCLUDE #STSDEF 3 


DECLARE 1 JPI_LIST STATIC EXTERNAL; & 

2& JPIUBUFIO;, /* Buffered I/0 count */ 
3 LENGTH FIKED BIN(15) INIT (4); 
3 CODE FIXED BIN(15) INIT (JPI$ WBUFIQ) +: 4] 
3 ADDRESS PTR: : 
3B RETURNULENGTH FIXED BIN(31) INIT (0)+ 
JPILCPUTIM;: /* CPU time ¥/ 
3 LENGTH FIXED BIN(15) INIT (4); 
3 CODE FIXED BIN(1i5) INIT (JIPI$_CPUTIM) + @ 
3 ADDRESS PTR»: 
3 RETURN_LENGTH FIXED BIN(31) INIT (0)+ 
JPILDIRIO, /* Direct 1/0 count ¥/ 
3 LENGTH FIXED BIN(15) INIT (4) INIT (JPI$_DIRIO)»> 4) 
3 CODE FIXED BIN(15); 
3 ADDRESS PTR: 
3 RETURN LENGTH FIXED BIN(31) INIT (0); 
JPI_PAGEFLTS; /* Page faults */ 
3 LENGTH FIKED BIN(15) INIT (4); 
3 CODE FIXED BIN(15) INIT (JPI$_WPAGEFLTS)? » 4) 
3 ADDRESS PTR» 
3 RETURN ULENGTH FIXED BIN(31) INIT (0)+ 
2 ENDLIST FIXED BIN(31) INIT (€0)5 


ine) 


ign 


ha 


DECLARE (TO+CLOCK_TIME) FLOAT BIN(24)} STATIC EXTERNAL] @ 
DECLARE FOR#SECNDS ENTRY (FLOAT BIN(24)) RETURNS (FLOAT BIN(24)33 


DECLARE (BUFIO;sEND_BUFIO;CPUTIM+END_CPUTIM:+DIRIO;+END_DIRIO, 
PAGEFLTS»END_WPAGEFLTS} FIXED BIN(¢31) STATIC EXTERNAL: 


DECLARE CPUSECONDS FLOAT BIN(24)3 
DECLARE 55%.NORMAL FIXED BIN(31) GLOBALREF VALUE S$ 


(Continued on page 19-27) 
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Sample Program 19-9 (Cont.): TIMRE and TIMRB 


TIMRE: ENTRY S 
JPT_UBUFIO.ADDRESS=ADDR(END_BUFIO) $ 16) 
JPT_CPUTIM.ADDRESS=ADDR(CEND_CPUTIM) : 
JPILBDIRIO.ADDRESS=ADDR(END_DIRIO} + 
JAPI_UPAGEFLTS.ADDRESS=ADDR(END_PAGEFLTS) 5 


IF SYS#GETIPI(¢+s+JPILLIST+++)"=SS$ NORMAL 7) 
THEN. PUT SKIP LIST (‘Error from SYS#GETIJIPI‘)3 


CLOCK. TIME=FOR$SECNDS(TO) § 

CPUSECONDS=(ENDLUCPUTIM-CPUTIM) /1O0E03 

RBUFIO=END_BUFIO-BUFIO5 

DIRIO=ENDB_LDIRIO-DIRIOS 

PAGEFLTS=END.PAGEFLTS-PAGEFLTS: 

PUT SKIP EDIT (’Times in seconds’+s’Page’;s’Direct’:s‘Buffered’) 
(AC207+;AC1T9I-ACIO) -AC1OI3s 

PUT SKIP EDIT (¢’CPU’,s ‘Elapsed’ +’Faults’+’T/O%+*T/0°) 
(AC19) A619) -AC1O-ACTO ACTOS S 

PUT SKIP EDIT (CPUSECONDS,CLOCK.TIME+PAGEFLTS:BDIRIO+BUFIO? 
(FOP st) -COLUMN (11) -FOS-1) -COLUMN( 21) FOF +0) -COLUMN( 31): 
FOF +0) sCOLUMN(41)-5F (0750303 


f#® After calling TIMRE: fall through here to re-initialize #/ 


TIMRB: ENTRY 3 
TO=FORS$SECNDS(QEQ) 5 
JPILBUFIO.ADDRESS=ADDRI(BUFIO) : 6] 
JIPITI_LCPUTIM,. ADDRESS=ADDR(CPUTIM) : 
JIPILDIRFIO.ADDRESS=ADDR(DIRIO?: § 
JAPILUPAGEFLTS.AGDRESS=ADBDR(PAGEFLTS? : 


IF SYS#GETIPIT 6 ++sJIPILLIST+++3°=SS¢. NORMAL 
THEN PUT SEIP LIST (‘Error from SYS#GETIPI‘ 15 
RETURN § 
EMD 3 
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Chapter 20 
Mailboxes 


A mailbox is a virtual input/output device that provides a means of communi- 
cation for images executing in different processes. Mailboxes are used by the 
operating system to initiate and record system operations; they can also 
provide communication facilities for user applications. 


This chapter provides: 
¢ Some general information on using mailboxes 
e Examples of simple procedures that perform input and output to mailboxes 


Note that this chapter provides only information that is pertinent to actual 
input/output to mailboxes and does not describe mailbox creation. There is a 
system procedure to create a mailbox, the Create Mailbox and Assign Chan- 
nel system service (SYS$CREMBX). For an annotated example of a call to 
this system service, see Section 19.4.2, “Mailbox Services.” 


20.1 Using Mailboxes 


The next few subsections provide information on how the system controls 
the creation and use of mailboxes and a typical use of mailboxes in an 
application. 


20.1.1 System Information 


When a program creates a mailbox, the operating system allocates dynamic 
memory to store control information about the device and to buffer input and 
output data. The ability to create mailboxes is controlled by two separate 
privileges: 


e The privilege to create temporary mailboxes (TMPMBX) permits a user to 
create a mailbox that is automatically deleted when the image that created 
it completes execution. 


e The privilege to create permanent mailboxes (PRMMBX) permits a user to 
create a mailbox that continues to reside in system memory until it is 
specifically deleted. 


20-1 


PROCESS A (CONTROLLING) 


— 


Creates the mailbox and gives it the 
logical name PLI_MAILBOX. The system 
gives it the device name MBA99- 


) 


Opens the file: 


PROCESS B 


~ 


Opens the mailbox for writing: 


OPEN FILE(F) OUTPUT RECORD 
TITLE( ’PL!I_MAILBOX’); 


wo 


OPEN FILE (MFILE) INPUT RECORD 
TITLE( PLI_ MAILBOX’); 


Continuously reads data and messages 
from the mailbox: 


LOOP: READ FILE (MFILE) INTO(M...REC);: 


GOTO Loop: 


nm 


Writes messages to the mailbox: 
WRITE FILE(F) FROM (MSG) ; 


When there are no more messages to 
write, closes the file: 


CLOSE FILE(F); 







PLI_MAILBOX 
a 






wo 





PROCESS C 
1. Opens the mailbox for writing: 


OPEN FILE (MAILB) OUTPUT RECORD 
TITLE(‘PLI._MAILBOX’); 


Writes messages to the mailbox: 
WRITE FILE(MAILB) FROM (M... TEXT); 


When there are no more messages to 
write, closes the file: 


CLOSE FILE (MAILB) ; 


N 


a 


Figure 20-1: Using Mailboxes 


20.1.3 Effects of the OPEN Statement 


When the TITLE option of an OPEN statement specifies the logical name of a 
mailbox; the run-time system associates a PL/I file with the mailbox device. 
The OPEN statement actually assigns an I/O channel to the mailbox; a chan- 
nel is an input/output path used by the operating system to perform data 
transfers. 


Every OPEN statement executed for the same mailbox assigns another 
channel to the device. The system keeps a count of all channels assigned to a 
mailbox so it knows when to delete the mailbox. 


20.1.4 Effects of the CLOSE Statement 


A CLOSE statement for a mailbox disassociates the PL/I file from the device 
and deassigns the channel to the device. When the count of channels assigned 
to a temporary mailbox reaches zero, the system deletes the mailbox and its 
logical name equivalence, if any. When the count of channels assigned to a 
permanent mailbox that is marked for deletion reaches zero, the system de- 
letes the permanent mailbox and its logical name equivalence, if any. The 
system service Delete Mailbox (SYS$DELMBX) must be invoked to mark a 
permanent mailbox for deletion. 


Each time a CLOSE statement is executed for a mailbox, the file system 
writes an end-of-file to the mailbox. When this end-of-file is encountered 
during an input operation, the ENDFILE condition is signaled. 
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The OPEN statement for the mailbox specifies that it is an input file and 
that its logical name is PLL_MAILBOX. 


LOGGER opens an output log file named MAILTEST.OUT. 


This procedure establishes an ENDFILE ON-unit for the mailbox. This 
ON-unit transfers control to the label LOOP, which is the main read loop 
of the procedure. This statement ensures that LOGGER will not be 
accidentally terminated if an ENDFILE condition is signaled as a result of 
a program executing a CLOSE statement to close the mailbox file. 


Each READ statement is followed by a test of the first field in the mailbox 
record. By application convention, when the value associated with the 
global symbol END__RUN is written to this field, it indicates that the 
program is complete. If this field contains any other value, LOGGER 
writes the record into the log file and loops to read another record. 


When the termination value END_RUN is received, control transfers to 
the label FINISH, where LOGGER closes both files and returns. 


Sample Program 20-1: Synchronous Mailbox Input/Output 


LOGGER: PROCEDURE: 


DECLARE (MAILFILE+OUTFILE) FILE: 


DECLARE 1 LOG_MESSAGE: 

TYPE FIXED BINARY(21:; 2) 
SYSTEM_TIME CHARACTER( 25); 
REQUESTOR CHARACTER(1S); 
STATUS FIXED BINARY 3113 


Pao fad Pa a 


DECLARE ENDLRUN GLOBALREF FIXED BINARY( 31) VALUE: 


OPEN FILE(MAILFILE) RECORD INPUT SEQUENTIAL © 
TITLE ¢’PLI_LMAILBOR (33 
OPEN FILE(QUTFILE} PRINT TITLE( ‘MAILTEST-.-OUT‘13 @ 


ENDFILE(MAILFILE) GOTO LOOPs /# Isnare end-of-file #/ 5] 


OP: 
READ FILE¢MATLFILE) INTO (LOG_UMESSAGE) 5 


IF LOG.MESSAGE.TYPE = END_LRUN THEN GOTO FINISH: @ 
PUT FILECOUTFILE? SKIP LIST(TYPE+-SYSTEM_TIME+REGUESTOR ; 


STATUS) 5 
GOTO LOOP: 


FINISH: 
CLOSE FILE(MAILFILE): 7) 
MLOSE FILECOUTFILE? 3 
RETURN § 
END 5 
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Sample Program 20-2: Asynchronous Mailbox Input/Output 


EMPTY BOA: PROCEDURE OPTIONS(MAIN) RETURNS (FIXED BINARY (31)035 


ZINCLUBDE SYS#¢ASSIGNS5 
f* Assign 1/0 Channel system service */ @ 
declare s¥ys#assign external entry ¢ 


chard) + /* device name or logical name #/ 

fixed bin¢idsi: /*® variable to receive channel number #/ 
fixed bin(3i)d} values /* access mode #/ 

char(#)) f*® associated mailbox name #/ 


oPtions(variable} returns(fixed binary(3i)34 


ZINCLUDE SYS#OI03 
f* Queue T/0O Request system service #/ 
declare sys#sio external entry ¢ 


fixed biné3l) values f* event flag number ¥/ 
fixed bint3i?d values f*® channel number #/ 

fixed binf3il} value: /* IT/0O function code #/ 
ary s+ : TfO status block #/ 


% 
entry values f* external AST Procedure #/ 
any value} * AST Parameter and I/O parameters #/ 


oFtions(variable) returns (fixed bin 3Bisis 


“INCLUDE SYS#WAITFR 3 
f* Wait for Event Flad system service #/ 
declare sys#waitfr external entry ¢ 
fixed binté31)} value} /* event flag */ 


returns (fixed binfBiiis 
ZUINCLUBGE #STSBEF 3: 
DECLARE MBRCHAN FIXER BINARY(15)3 


DECLARE (SS# ENDOFFILE:10¢ READVBLK +IO$M_NOW) FIXED BINARY(31) @ 
GLOBALRFEF VALUE: 
1 IO_STATUS»: 

WALUE FIXED (15); 

BYTES_TRANSFERRED FIXED(15) : 

MHOT_USED FIXEDS 31); 

-~SUCCESS BITC1) ALIGNED BASED(ADDR(TOLSTATUS. VALUE? 33 


bet 
TM ha ha fhe 


DECLARE MESSAGE CHARACTER(13233 © 


ie 


STS$VALUE = SYS$ASSIGN( ’PLI_MAILBOX’ +MBXCHAN::)4 @ 
IF “STS$#SUCCESS THEN RETURN (STS#VALUE) 3 


f* Use a DO-loor to read the mailbox: each 910 is followed 
by a test of the return status from 910+ then a wait for 
the I/O completion. Then: the Status value in the I/0 
atatus block is checked. If it contains SS# ENDOFFILE: 
return STS#SUCCESS. Otherwise:r return error value 

#/ . : 

DO WHILE (TO_STATUS.VALUE “= SS# J ENDOFFILE: 3 

STS#VALUE = SYS#OI0 (¢@1;+MBRCHAN: 6 
1O¢_READVBLK+10¢M_NOH+ © 
IG_STATUS+++ @ © 
ADDR (MESSAGE) -LENGTH(MESSAGE} +++ +34 
IF “STS#SUCCESS THEN RETURN(STS#VALUE: 5 


(Continued on next page) 
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Chapter 21 
Accessing Files on a Network 


If your system supports DECnet-VAX facilities, and your computer is one of 
the nodes in a DECnet-VAX network, you can communicate with other nodes 
in the network by means of standard PL/I input/output statements. These 
statements provide two distinct types of network operations: 


e Remote file access lets you read and write files on a remote node as if the file 
were on your local system. 


¢ Task-to-task communication lets you exchange data directly with a job that 
is executing at a remote location. 


Examples of both remote file access and task-to-task communication using 
PL/I statements are given in this chapter. For complete details on using the 
DECnet-VAX facilities, see the DECnet-VAX User’s Guide. 


21.1 Remote File Access 


To access a file on a remote system, you include the node name in the file 
specification of the external file you identify for the execution of the program. 
For example: 


BOSTON: :DBAOQ:CMALCOLMITEMPS.TST 


This file specification identifies the file TEMPS.TST in the directory 
DBAO: [MALCOLM] on the node BOSTON. 


You can specify a node name in a file specification in either of the following 
contexts: 


¢ In the file specification in the TITLE option of an OPEN statement 


e In the equivalence name you assign to a logical name before running a 
program that refers to a file by logical name 


SOURCE (HOST) SYSTEM TARGET SYSTEM 


@ OPEN FILE (TASKFILE) RECORD OUTPUT —————398- LOGGER.COM @ 


TITLE ('HSTN"MALCOLM YES": "TASK LOGGER’ ’): 


The OPEN statement initiates task-to-task communication 
with the target node by specifying a task name, LOGGER, 
in the file specification. The network program uses the 
default directory of the user MALCOLM, specified in 

the network file specification, to locate the command 

file LOGGER.COM. 


The cooperating task on the target network specifies 






$RUN COPYTASK & 


The network program submits the 
specitied command file to the 
batch job queue on the target system. 









This command file executes the 
program image of the cooperating 
program. 







the logical name SYS$NET in the OPEN statement that OPEN FILE (NETFILE) RECORD SEQUENTIAL 
completes the network connection between the two INPUT TITLE (‘SYS$NET’): @ 
tasks. When this OPEN statement completes. communication 


can begin. 


6 


WRITE FILE (TASKFILE) FROM (TASK REC): ————————3™—_ READ FILE (NETFILE) INTO (LOG REC); 


All communication across this network link 

is synchronous. Following each WRITE request 
by the source task, the task must wait until 
the target task reads the record. 


CLOSE FILE (TASKFILE): @ 


The CLOSE statement destroys the logical link 
and terminates the task-to-task communication. 


Figure 21-1: 


Network Task-to-Task Communication 


The following notes are keyed to Figure 21-1: 


li 


The program that initiates the communication is called the source task. It 
requests a network connection to a target task by specifying a task name 
in a file specification that contains a node name. This OPEN statement 
initiates the request and associates a PL/I file with a network logical link 
created by DECnet. 


DECnet locates the command file LOGGER.COM on the remote node 
specified in the OPEN statement. The name of the command file is speci- 
fied by the task specification string, TASK=LOGGER. DECnet submits 
this command file for execution on the remote system. 


The command file must contain the command necessary to initiate the 
execution of the cooperating program, COPYTASK. 


The cooperating target task must complete the connection to the source 
task by executing an OPEN statement to open the file 
SYS$NET. SYS$NET is a logical name assigned by DECnet to the net- 
work job that identifies the source task’s node and process. 


After the logical link is established, the cooperating programs, or tasks, 
read and write data using the PL/I files associated with the logical link. 


When either program executes a CLOSE statement for the file, the logical 
link is broken and an end-of-file record is written to the cooperating task. 
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The following notes are keyed to Sample Program 21-2: 


1. The image file TARGET.EXE contains the compiled and linked code for 
the procedure TARGET_TASK. The declarations in the procedure 
TARGET_TASK include the files INFILE and OUTFILE, a structure 
into which messages will be read across the logical link, and a message 
field from which data will be written to the output file. 


2. The procedure establishes an UNDEFINEDFILE ON-unit for any error 
conditions that occur creating the logical link; at the label FILE_ 
ERROR, the status code is reported and the procedure exits. 


3. The ENDFILE condition provides for a normal termination of the logical 
link. When the program SOURCE_TASK closes the file TASKNAME, 
an end-of-file condition is returned on the next read attempted in 


TARGET_TASK. 


4. The first OPEN statement opens the file SYS$NET; if this open is 
successful, the network connection is established. The second OPEN 
statement opens the file TASK.DAT, the output file that will be created 
at the target node, in the default directory for the user name BEANS. 


5. ‘The read loop in this procedure reads a message from the logical link, edits 
the data, and places the record in the output file. 


Sample Program 21-2: A PL/I Target Task 


TARGET.TASE: PROCEDURES @ 


DECLARE (INFILE s-QUTFILE? FILES f® Files #/ 
DECLARE to LOGLM Es ft 






5, 


obtructure 


1 OMAR Y DAG 4 


DECLARE MESS ba Ee fe Uariable to convert messade #/ 
PUT STRINGOMESSAGE? EBIT(’ °) 8 € Bop a a 
ON UNDEF INEDFILE(INFILE? GOTO FILE.ERROR? /* Network errors #/ @ 
QM ERNDPFILE? TNFILE: GOTO FINISHS /# Normal comeletion #/ & 
MPEN FILE ¢0NFILE? RECORD SEQUENTIAL INPUT 
TITLE (‘’SYS8NET C33 ‘# Oren SYS#NET #/ @ 


MPEN FILECOQUTFILE) RECORD SEQUENTIAL OUTPUT 
TITLE? ‘TASK: DAT’) 45 (# Orpen outeut loa file #¢f 








LEIP s 
FEAD FILES INFILE: INTO (LOGI MESSAGE 3 : 
FUT STRING(MESSAGE: EDIT(STATUS-TERT: ¢FiGi-xsAbS 
WRITE FILE@QUTFILE: FROM (MESSAGE) 
GOTO LOOP: 
FINISH: 
CLOSE FILECINFILE? 3 
MLOSE FILES QUTFILE: 5 
RETURN § 
FILE_ERFOR: 
PUT SERIF LISTi‘Ineut file error’ -OMROGES dG 
RFETUREH 4 





ENO 4 
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Chapter 22 
Calling SORT Procedures 


VAX-11 SORT is a utility program that provides a range of sorting capabili- 
ties and options. You can use the SORT program in two ways: 


e At the DCL command level, you can invoke the DCL command SORT. By 
specifying input and output files and sorting options, you can perform 
sorting functions interactively from the terminal. 


e In a PL/I program, you can call SORT procedures. These procedures, or 
subroutines, are summarized below. 


For complete details on using SORT, see the VAX-11 SORT User’s Guide. 
For additional information on invoking procedures that are written in lan- 
guages other than PL/I, and for an explanation of ways of passing parameters 
to non-PL/I procedures and testing the return status from a procedure, see 
Part III, “Procedure Calling and Condition Handling.” 


22.1 Declaring SORT Procedures 


The default PL/I text library PLISYSDEF.TLB contains declarations for 
SORT procedures as external functions. The text module names have the 
forms: 


SORS$name 
where SOR$name is the name of the SORT procedure. Thus, to declare a 
SORT procedure, specify a % INCLUDE statement as in this example: 
%INCLUDE SOR$PASS_FILES3 


The compiler, by default, locates the module SOR$PASS__FILES in 
PLISYSDEF.TLB during the compilation. 


All SORT parameters are passed either by descriptor or by reference. 


SORT procedures do not require you to specify commas for omitted trailing 
arguments. 


All SORT procedures are declared with the attribute RETURNS (FIXED 
BINARY(31)). You must invoke the procedures as functions, and you may 
test the value returned as an indication of success or failure. | 
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Sample Program 22-1: Sorting Files 


SORTEM: PROCEDURE RETURNS (FIXES 4 


# Tnelude the declarations of the SORT procedures reauired 
for a sort using the file interface. #/ 


“INCLUDE SOR#PASS FILES 1) 
declare sortpass.filles external er ( 
character (#); 
charactar(#}: 
fixed binary? 
fixed binaryé 


ot 
co 


imfPut file #/ 

output file #/ 

OutrPut file ordanizatian #/ 
output file recore at # 
fixed binaryi vi: output file bucket 
fixed binarryrtiSi: output file block Ze 
fixed binary (18); f* output file maximum res 
fixed binary(3Bli: output file allocation #7 
fixed binary (3133 f file oFtions ¥/ 


oe ae 


Pde f 
ee 
4}? 


oh. 


vie sie 







ra Oo 





sie 


sit 


getions(variable) returns (fixed binarytadiias 


BIACLUDE SORSINITOSORT 4: 
declare sorfinitosort entry 


f*® sort Key buffer #/ 
binaryfiSad; f* longest record 
fixed binaryt3l): f*® ineFut fille size 
fixed binaryé #7} + f# number of work 
fixed binary( 7); f*# type af & 
fixed binarryi yi; f#® Kes 
entry value: f* come 
t 





T 

ze 
co 160m routine #/ 
bittBSi aligned: f* soar etd 


options (variable) returnsifixed binary(3iiia 
SINCLUGE SORSSORTUMERGE : 
RINCLUBE SORSENDSO 


declare sortendwisort 






returns(fixed binary (3133 
“INCLUDE @STSGBEF : 


Declare the input and guteut files 
which must he defined before the -e 


toe 


ros 


DECLARE INPUTOUPILE CHARPACTER(6) STATIC INITé’INFILE’): 2) 
QUTPUTLPFILE CHARACTER (?) STATIC INIT(‘OUTFILE’ i: 

f* Declare the Key buffer array reguited to sort the first &o 

chatacters of any record. This ‘a 

gtructure to clarify the examele. 


ip Bete 





DECLARE i KEYOBUFFER STATIC: 
NUMBERLOPLKEYS FIXED BINARY (153 INITC1): 
= KREYOTYPE FIRED BINARY (15) INIT¢1li: £# character #/ 
2 KEYOORBER FIRED BINARY (15) INIT(O}; £# ascendinad order #/ 
START.POS FIXED BINARY(15) INIT¢(1i: 
& KREYOLENGTH FIXED BINSRY(153 INIT(80) ; 
LONGESTOUWRECORG FIXED BINARY(15) STATIC INIT¢eois 








f# Declare global avinbol names for FMS values to define the output file #*/ 
DECLARE (FABSC_LUGR: FABSC.REL? GLOBALREF FIRED BINARY(31) VALUE s 4) 


DECLARE 





CORD. TYPE FINED BIN(?), 
FILE.GRG FIXED BINARY(7)3 





RECORO TYPE = FARSC 
FILEWORG = FABEC Le 








(Continued on next page) 
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Sample Program 22-2: A Record Sort 


This Progtam sor 


5 the file STATE_FILE based on the field 
CAPITAL.NAME in 


ts 
each record. 


Logical name equivalences are required for the input file STATEWFILE 
and an outeut file SORTEDBLFILE. 
ef 


STATESORT: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY(31)35 


Declare SORT routines 


af 1) 

“INCLUBE SOR#INITUSORT: 

declare sor€initwsort entry 
ATIY + f® sort 
fixed binary? 
fixed binaryit Gli; f# input file size #/ 
fixed binar; } f# number of work files #/ 
fixed binar: = : 
fixed binaryiy} 
aniry valu 
bitt¢S3s) al 


¢ 


buffer #/ 
Gcord lengasth #/ 


i 
Te 


She f® longe 


2 
— 





bt {Tl 


ahh oa 


on ToOutine #/ 


oFtionsfvariable) returnsi fixed binary(3iidia 


SINCLUDE SORSRELEASE_FEC 3 
+ 


declare sor: 


To 
. 

+ 

Tl 

mt 

i 

_ 

Th 


Telease rec 


Tot 
“out 
mat 
ase | 
ot 


at 
af 

+ 
i. ot 


‘ 


r record buffer #/ 


ord =#/ 


wh tel 


qd binarytis 
d tinaryd 


olnter! fe 


A 
Cs a 
fovet 
me iT 
7 
took 
io) 
mn 
tho oh 


i 
fu oh 
po 
co 


a 
1A 





nt 
Los I oe RE 


‘Th rr 
itt mt 
ae 


Wi 
mt 
tb, 
ot 
iT 
oh 
mi 
ot 
mh 
i 


turns (fixed binarvia 


wt: 
IT 


“INCLUDE SORSSORT_UMERGE 5 
declare sortsortlmerge external enter 


turns tfixed binarryéSiiis 


mt 
m 


ne 


SORSRETURN REC 


TEreturnwtec ext 


mo 
mi 
m 
es) 


TTL teme 
me Yi 


it 
mm TT 
my 
“it 
‘ti 

i 
~+ 
Ti 
rm 
peat 
iTt 
~P 
“I 


cL 
iT o™ 
iit 


Letar for record buffer #/ 





fixed binarrtiSi.: 
fixed binaryt1lBi-: 
FOLMtar: 
ed binaryi lS) 3 


bee ID 


co. 
kh 





MPa Pe fea 


M$ hh ee 


it 
ct 


fobs 


oPtiansfuariable) reaturnst(fixed binaryt31ias 


“INCLUDE SORSEND_SORT 3 
declare sortend isart external entry 


ory 


rethurnst fixed binaryéSiii 
“INCLUDE #5STSDEF 3: 


(Continued on page 22-7) 
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Sample Program 22-2: (Cont.) A Record Sort 


DECLARE SS#.ENDOFFILE GLOBALREF FIXED 
EQF BiIT¢i)3 


a BINARY (31) 


‘@ 


EFQF = ‘O°BS3 
i * 
Key buffer and data for SORT routines 
*/ 
DECLARE 1 KEY BUFFER STATIC: 
© NUMBER_LOF_LKEYS FIXED BINARY (15) INIT¢1})+ 
2 KEYOJTYPE FIKED BINARY ¢€15) INIT(1)+ /# character 
2 KEYOUWORDER FIXED BINARY (15) INIT(a): /# 
2“ STARTUWPOS FIKED BINARY(15) INIT(e5); e 


KEYOJLENGTH FIXED BINARY(15) INITCEO) + 
LONGESTURECORD FIXED BINARY(15) STATIC INIT(196)+ 4] 
KEYFIELD FIMED BINARY (7:3; /* Code ta decide sor 
RETURNULENGTH FIXED BINARY (15)5 /%* Feauired Parameter 

/* Declare a buffer each record be passed ta 


5) 


to construct ta 


DECLARE i STATE RECORD: 
7 KEYFIELD CHARACTER(20) + 

STATE + 

NAME CHARACTER (20) + 
FOPULATION FIXED BINARY(31:; 
CAPITAL + 

4 NAME CHARACTER ¢ 
4 POPULATION FIXED 
LARGEST_CITIES( 2}; 
4 NAME CHARACTER(S); 

4 POPULATION FIXED BINARY( 31); 
SYMBOLS: 

4 FLOWER CHARGCTER 
4 BikG CHARACTER 


d 


complete recar % 


a 
> 
ra 


rae 
alld ¢ 


BINARY (31) + 


i3Ba): 


(343 


BECLARE 1 RECORDUDESCRIPTOR: 
® LENGTH FIRED BINARY( 15); 6 
2 FILLER FIXED BINARY(15); 
* ADDRESS POINTER: 
Input and output files 
“/ 


DECLARE STATE.FILE FILE INPUT RECORD 
SORTEDLFILE FILE RECORD 


SEQUENTIAL : 
OUTPUT SEQUENTIAL: 
call SOR#INIT_SORT 


STS#VALUE 
IF “STS#SU 


R#INITUSORT(CKEY BUFFER +-LONGEST RECORD: : 
S THEN RETURN(STSS$VALUE) 5 


Oo 
c 
o 


= § 
CCE 
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ascending order 


heya #/ 


*/ 


t #/ 
# f 


SORT #/ 


(Continued on page 22-9) 
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Sample Program 22-2: (Cont.) A Record Sort 


i* 
Enter DO-loop to read the input file STATE_FILE. Then: call 
SOR#RELEASE_REC. The record consists of the Key field concatenated 
with the contents of STATE. 

#/ 


OPEN FILE(STATE_FILE) 3 
RECORD_UDESCRIPTOR.LENGTH = 1963 8) 
RECORD_UDESCRIPTOR.ADDRESS = ADDR(STATE_RECORD?) : 


GON ENDFILE(STATE_FILE) EOF = ‘'1°B3 


READ FILE (STATE_FILE) INTO(STATE?) 3: 
DO. WHILE (*EQF)3 
STATE_RECORD.KEYFIELD = CAPITAL.NAME; © 
STS$VALUE = SOR#RELEASE_REC ¢ 
RECORD_DESCRIPTOR) 3 
IF “STS#SUCCESS THEN RETURN(STS#VALUE) 5 
READ FILE‘STATE.FILE?: INTOCSTATE?) 3 
END 5§ 
CLOSE FILE(STATE_FILE} 3 
PUT SKIP LIST( ‘*##*#* ALL RECORDS RELEASED’) 3 


Call SOR#SORT_MERGE to sort the records that were released 
. STS$VALUE = SORPSORT_UMERGE( 33 © 
IF “STS#SUCCESS THEN FETURN(STS#$¥UALUE} + 
Loor through the DO-drour to det back each record and write it 
to the sorted ogutrut file. 
STS$VALUE = 1: 
OPEN FILE¢SORTEG_LFILE} OUTPUT: @ 
RPECORD_DESCRIPTOR.LENGTH = 176: 
PECORD_DESCRIFTOR. ADDRESS = 4RBR(STATE:: 
DO WHILE ¢STS#VALUE “= SS# ENDOFFILE:} 3 @ 
STS#vaLueE = SORSRETURN_RFEC(CRECORPD_GESCRIPTOR+RETURNULENGTHi 5: 
IF STS#SUCCESS THEN WRITE Puee SORTED. Sag FROM ¢STATE? + 
ELSE IF “STS#SUCCESS & (STS#USGLUE “= SS#_. ENDOFPFILE 3 
THEN FETURN(STSEVALUE: 5 
END S$ 
CLOSE FILE (‘SORTEG_LFILE:}: 
Call SOR#END_SORT to finish uF 
t; 
STS#VALUE = SORtENDG_SORT(} 5 ® 
IF “STS#SUCCESS THEN RETURN(STS#¥4LUE)} 3 
RETURNG 133 f#® successful completion #/ 
All errors come here to return to the command level with the 
status value af the error in FO. 
ERROR: RETURN(STS#VALUE: 3 
END 4 
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Appendix A | 
Compiler Listing Format 


This appendix provides sample annotated listings from the VAX-11 PL/I 
compiler. It illustrates: 


e Effects of the options in the /ENABLE qualifier 
e The machine code generated by PL/I 


Figure A-1 illustrates the default listing and describes the information 
provided in the listing. 


Figure A-2 illustrates a storage map of the same program. The VAX-11 PL/I 
compiler generates a storage map if you specify /ENABLE=LIST_MAP on 
the PLI command; it generates a cross-reference listing in the storage map if 
you specify /CROSS_REFERENCE. | 


Figure A-3 illustrates the statistic summary generated if the 
/ENABLE=LIST_STATISTICS qualifier is specified. 


Figure A-4 illustrates a portion of a listing of a program compiled with the 
/MACHINE_CODE qualifier. 


ee a a 


The following notes are keyed to Figure A-1: 


1. The name of the first level-one procedure in the source program and its 
identification. If the main procedure did not specify OPTIONS(IDENT) 
the compiler uses the default identification V001. 


2. The date and time of compilation, and the version of the compiler that 
was used to compile the program. 


3. The date and time that the file containing the source program was 
created, and its full file specification (to a maximum of 44 characters). 


4. The page number of the listing file and the page number of the source file. - 


5. Compiler-generated line numbers. The compiler assigns a number to each 


line in the source program, including comment lines and lines read from 
INCLUDE files. 


Note that these line numbers do not necessarily correspond to the line 
numbers, if any, assigned to the file by an editor that is line-number 
oriented. 


6. The nesting level, or depth, of each statement. The outermost procedure is 
always level 1. Additional level numbers are assigned to statements within 
internal procedures, begin blocks, and DO-groups. 


7. A vertical bar (:!) character indicates a line that contains only a comment. 


If the program is compiled with the qualifier /KNABLE=LIST_INCLUDE, 
the “INCLUDE statements are followed by the contents of the INCLUDE 


files, with line numbers, as follows: 


“*INCLUBE STATES 
DECLARE 1 STATE BASED (STATE_PTR?): 


= NAME CHARACTER (20) + /*® Primary Key ¥/ 
2 FOPULATION FIXED BINARY(313+/* 3rd alternate Key #/ 
2 CAPITAL» 


3 NAME CHARACTER (29) + 
3B POPULATION FIXED BINARY( 31) + 
2 LARGEST_CITIES(2)+ 
3 NAME CHARACTER(30); 
3 POPULATION FIXED BINARY(31}: 
2 SYMBOLS, 
3 FLOWER CHARACTER (30), f# secondary - ist alternate - key #*/ 
3 BIRD CHARACTER (30); f/* tertiary - 2rd alternate - Key ¥/ 
STATE_PTR POINTER: 
STATE_FILE FILE3: 


The listing page shown in Figure A-2 illustrates the storage map page of the 
program listing. This page is generated if either /ENABLE=LIST_MAP or 
/CROSS_.REFERENCE is specified on the PLI command. The notes keyed 
to Figure A-2 appear below it. 
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FLOWERS 
Wood 


Begin Block on line 36 


Identifier Name 


INPUT_FLOWER 


Psect Synopsis © 


Psect Name 


$CODE 
SDATA 
SYSIN 
SYSPRINT 
STATE_-FILE 


Procedure Definition Map 


Line Name 

3 FLOWERS 
23 BEGIN 
36 BEGIN 
49g BEGIN 


Command Line @ 


automatic 





11-JUN-1980 15:43:51 YAX-11 PL/I Vi.o Page 3 
Li-JUN-1980 15:42:57 ~DB7:(MALCOLMIFLOWERS.PLI517 


Size Line Attributes 


ae by a? Gharacter(3O)+ varying+s unaligned 


Attributes 


Ltian-inderendent + 
Ltiaon-inderendent + 
Ltion-inderendent + 
itlon-inderendent + 
lon-tinderendent +: 


ALIST=STORAGE/ENAB=LIST_MAP FLOWERS+STATETHT/SLIBRARY 


Figure A-2 (Cont.): Compiler Storage Map 


1. The compiler lists the names of all external entry points in the module and their attributes. 


2. For each procedure in the source program, the compiler lists each declared name, giving: 


- The user-specified identifier of the name 


yeullog Burysry Jepidwuoy 


s-V 


- The storage class to which the name belongs 
- The amount of storage allocated for the name, where: 


bi — indicates that the size is given in bits 
by — indicates that the size is given in bytes 


- The line number on which the declaration of the name appears. Note that if a declaration 
is continued on more than one line (for example, in a structure declaration), the line number 
is always the number of the line on which the DECLARE statement is terminated. 


relocatable+ share: execute, read 

relocatable; read+ write 

overlays relocatable; global: share: read+ write 
gQuerlay+s relocatable: global: share: tead+s write 
overlay: relocatable+ global+s share+ read: write 


~ The data type attributes of the name. If the name represents a member of a structure, the 
attributes are preceded by the offset of the structure member from the base of the structure. 


The Program Section (Psect) Synopsis lists the program sections created by 
the compiler and their attributes. For an explanation of program sections and_ their 
attributes, see Section 19.1.2, ‘‘Program Sections Created by PL/I.” 


The Procedure Definition Map lists each procedure and begin block in the program, giving the 
line number on which the block is defined. 


The Command Line shows the PLI command string that was processed, including input files, 
qualifiers, and library files. 


JeWIOY SUIYSI'T JeTIdui0;d 


Figure A-3 illustrates the statistical summary that PL/I includes in the listing 
if the /ENABLE=LIST_STATISTICS qualifier is specified. The following 
notes are keyed to Figure A-3: 


1. The compiler accumulates statistics for each phase of its operation. 


2. For each phase of the compiler’s operation, it lists I/O, memory, and CPU 
time usage statistics. 





FLOWERS 11-JUN-1980 15:44:16 WAX-11 PL Yi.a 
WOOL 1i-JUN-1980 15:d2;:37 ~GEB?:CMALCOLMIFLOWERS.PLIG1? 
ie Na i cee a Cae es a Loe Sy ae, mm |e aa bea sei eh ee! 
| Performance Tndicators | 
fa ee an Ui, Keen ts deg isch? Sec Sy Gna als adbe alas Se ake) “eh Shad ue ats add 
Phase 1) (2) buf aifa dir i/o padgeflt virtmem workset crPutin 
Pass 1 totals a a 0 AG 
declare totals a a a 16 
Fass 2 totale O Oo 16 63 
live-analysis o o Oo i3 
rearder invariants a 0 t 12 
eliminate redundancy a O o iG 
eliminate assignments o o a 1 
arptimizer totals o a 0 55 
allocator totals 1 o a 16 
fenerate code list o a Ga 55) 
register allocation 0 o 1 o a 
Peephole oftimizatian oO 0 o o 6 
branch Jump resolution a G 2 o 3 
write obJect module 0 1 Za oO 3 
code generator tatals 1 2 1G? 6a 8s? 
total compilation ? 5 ga5 Ba gas 





63 lines compiled 
comPilation rate was 1073 lines Per minute 


Figure A-3: Compiler Performance Statistics 


If you specify /MACHINE_CODE when you compile a PL/I program, the 
compiler prints the generated assembly language code and object code in the 
listing. The notes keyed to the sample machine code listing in Figure A—-4 
appear below the figure. 


mi 
— mt 


yeWIOY SUIYSTT JetiIdwuo0dg 


52 FF7E CD 
50 FF7E CD 
51 52 


FLOWERS 
Yoo 


27 
28 


o1 0A 


ELSE 
PUT SKIP 


Pl fa 


51 30 
O23 AF GC 
ooga 


ce?7c 

5E FEFS CE 

SC oo000ngogoo EF 
30 

FE AD O1 

S2 FE AB 

Da 

OOoOoOGOOos EF 
50 FEFS CF 

Bb Ge. 
oHaggcdoGoOs EF 


FFVE CO 


oooo00gBa BF 


LIST ¢ 


DO 


Si. 


SE 
SE 
7C 
Bo 
9E 
7C 
16 
SE 
3c 
iG 
SF 
0G 


QOOEG 
QOEA 
QOOEC 
OOF? 
QOOFG 
OOF 
o103 
O108 
op,oo 


o110 
O116 
OL11B 
QO11E 
O124 


‘Error on 


O12A 
O1ZA 
O120 
O1a1 
o134 
goiad 
O136 
O136 
O142 
o1dd 
O14. 
o14¢c 
OL4E 
O154 
O158 
GOLSE 
QO162 
G166 


mova 
clra 
Jah 
Fushab 
FuUSHL 
calls 
moO tl 
mouak 


mowgzid 
Li-wtUN- 1 
ti-JUN- 1 
Jeb 


mouwak 
mouzued 
web 


Jin 


key ;sONEEY() + ° 





weg. 3 

uogd:ds 
Pert ry 
woavab 
movab 





Wola 
weak 


elra 














Figure A-4 (Cont.): Machine Code Listing 


1; 


err 


~O2¢fp)are 
r3 
PLI®PUTFILE 
-QOBE(fP) 
#90 
#2+PLISONKEY 
~-QOB2(fpiare 
-ONBE CPP). ro 
reeri 


ga 
foo 


13:50:20 
15:42:57 


WAX-11 PL/I V1.0 
~DB7:*CMALCOLMIFLOWERS.PLI517 


PLI&PUTLISTYUCHA 
$CODE+SCe+ra 
#Aeri 
PLI#PUTLISTCHAR 
PLI#PUT_UEND 


or no.’ -sQONCOBE( 335 


freri 

fap}eved.d . 
uo. 3 
vuod.,coder"miduriurrZ-rrB:rrGdsrS-rGerili: 
~O1LOBRiseiyse 

SYSPRINT+ ape 

ra 

1--O2¢0fP) 


~-O2tfriere 

















ra 
PLISPUTFILE 
£CODE+S0-r0 
#iDsrl 


PLI&PUTLISTCHAR 





The machine language code is generated in line with the PL/I source 
statements. Thus, you can see the code that is generated by each state- 
ment following the statement itself. 


The listing shows, in hexadecimal, the object module location of each 
generated statement directly to the left of the machine language code. To 
the left of the object location is the object code generated by the VAX-11 


PL/I compiler. 
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Appendix B 
PL/I Messages 


This appendix describes the messages produced: 
e By the VAX-11 PL/I Compiler 
e By the VAX-11 Run-Time System 


For a description of the format of messages produced by the compiler, see 
Section 2.3, “Compiler Diagnostic Messages and Warning Conditions.” For a 
description of the format and information provided by run-time messages, see 
Section 4.1.2, “Run-Time Errors.” 


B.1 Compiler Messages 


The diagnostic messages produced by the VAX-11 PL/I compiler are listed 
below, alphabetized by identification. Within the text of a message, an item 
in italics represents data that is supplied by the compiler to provide specific 
information about the error. 


The description of each message gives the severity, followed by additional 
explanatory text and suggested action. For example: 


Warning. A division operation contains a fixed-point ... 
Here, ““Warning” indicates that the message has a severity level of Warning. 


Compiler messages with severities of error or fatal require that you recompile 
the program after correcting the source text. 


Note that the VAX-11 PL/I compiler also writes messages whose text it shares 
with other VAX/VMS programs; these messages are almost always self-expla- 
natory and are not listed in this appendix; see the VAX/VMS System Mes- 
sages and Recovery Procedures manual for descriptions of these messages. 


ARITHSYN Invalid syntax in an arithmetic constant. 
Error. The statement contains an arithmetic constant that is incorrectly specified. 


User Action. This message may be followed by additional messages that provide syntactic reasons for the 
failure. Determine the type of constant required in the statement and the correct way to specify the 
constant. Correct the statement. 


ARRAYBYVAL An argument corresponding to an array, structure, or area 
is not a reference. The procedure/function is ““name”’. 


Error. PL/I can pass aggregates and areas only by reference; thus, this error occurs when the parameter 
descriptor for an external entry or the parameter declaration for an internal procedure specifies a structure, 
dimension, or area that does not match the argument specified. 


User Action. Correct either the parameter descriptor or the declaration of the argument. 


ARRAYOVFL FIXEDOVERFLOW occurred in calculating the multipliers or 
virtual origin of the array “array-name’’. 


Error. In an array with constant bounds (for some or all of its dimensions), the FIXEDOVERFLOW 
condition occurred when the compiler tried to calculate the multipliers and virtual origins of the array. 


User Action. Check that the values specified for the array bounds are correct. Avoid using lower bound 
values that are very large numbers. 


ASSIGNCVT Implicit conversion in an assignment, expression 
has been converted to a data-type target. 


Warning. The data type of the indicated expression does not match the data type of the target variable in 
the assignment and the PL/I compiler has converted the expression to the data type of the target variable. 
This situation may or may not constitute an error. 


User Action. To avoid this message in circumstances in which you want the compiler to convert the 
expression to the data type of the target, use an explicit conversion built-in function (for example, CHAR- 
ACTER, BINARY, or FLOAT). You can also suppress the message by compiling the program with the 
/NOWARNINGS qualifier. 


ATTRNOTSPC Incomplete attributes have been specified for “variable-name’’. 
Error. Something is missing in a declaration. 
User Action. Correct the declaration. 


BADAGGARG The argument “argument” does not match the 
corresponding array, structure, or area parameter as is required by 
the rules for passing such arguments by reference. 


Error. An array dimension or a structure declaration specified in a parameter descriptor does not match 
the corresponding dimension or structure of the variable specified in the procedure reference. For example, 
this error occurs if a parameter descriptor specifies a two-dimensional array and the procedure reference 
specifies the corresponding argument with a reference to a three-dimensional array. 


User Action. Determine whether the parameter descriptor correctly specifies the data type, dimensions, 
and structure of the required parameter. If so, correct the declaration of the corresponding argument or the 
corresponding argument reference. If the argument is specified correctly, correct the parameter descriptor. 
If the procedure is a non-PL/I procedure, use the ANY attribute in the parameter descriptor. 


BADANYARG A procedure argument, expression, is not valid for passing 
to the corresponding parameter, which was declared as ANY or ANY VALUE. 


Error. A parameter descriptor specifies ANY or ANY VALUE, but the argument list specifies an expres- 
sion that is not valid for these argument passing attributes. For example, this error occurs when an 
expression whose value cannot be contained within 32 bits is specified for a parameter declared with the 
VALUE attribute. 


User Action. Determine how the argument is to be passed and correct either the parameter descriptor or 
the argument reference. 
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BADCLATTR ‘name’ is declared with duplicate or conflicting attributes. 
“attribute” conflicts with “attribute’’. 


Error. This error occurs when conflicting attributes of any type are specified. Some examples of errors that 
produce this message are: 


e When file description attributes are specified with data type attributes, or are specified for file variables 
or file parameters. 


e When the VALUE attribute is specified for any variable for which no data type attributes are specified or 
is specified with the READONLY attribute. 


User Action. Determine which are the correct attributes of the name and remove the invalid attribute from 
the declaration. 


BADCLSLABL The closure label in this statement does not match the 
label prefix of the containing DO, BEGIN, or PROCEDURE block. 


Error. Multiple closure is not permitted in VAX-11 PL/I. Each DO, BEGIN, and PROCEDURE statement 
in the program must have a corresponding END statement. 


User Action. Verify the label on the END statement in error. The label must match the label on the most 
recent DO, BEGIN, or PROCEDURE statement that does not already have a corresponding END state- 
ment. 


BADCODE Invalid code generation sequence. 
Fatal. An internal compiler error occurred. 


User Action. Gather as much information as you can about the conditions in effect when the error occurred 
and submit an SPR. 


BADCOMPARE Invalid comparison. The operands of relational operators must both be 
arithmetic values, string values or compatible noncomputational items. 
Noncomputational data can only be compared for equality. 


Error. A variable or value of a noncomputational data type is specified in a relational operation using the < 
or > operators or forms of these operators. For example, this error occurs if you use pointer or file variables 
in a comparison other than equality or inequality. 


User Action. Verify that the correct variable references are specified in the expression and that the 
statement does not violate the rules for operands of relational operators. Correct the statement. 


BADCONARG The first argument, expression, of a conversion 
built-in function is not a computational value. 


Error. The indicated argument reference or expression does not have a computational data type and 
therefore cannot be converted to the computational data type result of the function. 


User Action. Correct the argument list for the function. 


BADENVAL Invalid argument in an ENVIRONMENT option. 
A value-type was not found where expected. 


Error. An ENVIRONMENT option requires either a restricted integer expression, a Boolean expression, a 
character string, or a variable reference. The statement in error contains an ENVIRONMENT option that 
specifies a value that is not consistent with its type. For example, this error occurs if a character-string 
argument is specified for the MAXIMUM__RECORD__SIZE argument. 


User Action. Determine the data type required and correct the ENVIRONMENT option. 
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BADPSECT The psect specified in this statement has 
conflicting READONLY attributes with another definition 
of the same psect. 


Warning. A variable declared with the GLOBALDEF attribute and with a program section name specifies 
the same name for the program section as another global symbol. However, one declaration contains the 
READONLY attribute and the other does not. 


User Action. Determine whether the progam section can be declared with the READONLY attribute. If so, 
specify READONLY in all declarations that specify this program section. Otherwise, place read-only and 
read/write global symbols in different program sections. 


BADRETVAL The value, expression, in a return statement 
is not valid for conversion to the data-type function type. 


Error. The indicated return value specified in the RETURN statement does not have a data type that is 
valid for conversion to the data type specified in the corresponding returns descriptor. 


User Action. Determine the data type that is to be returned by the function and correct either the returns 
descriptor or the RETURN statement. 


BADSTRDCL ‘name’ is an apparent structure member, 
but does not immediately follow a variable with a 
level number. 


Error. A structure is incorrectly declared, or a variable declaration is preceded with an extraneous integer. 


User Action. If the variable is a member of a structure, verify that the structure declaration is properly 
numbered and properly punctuated. The first level number in a structure declaration must be 1. If the 
variable is not a member of a structure, check the syntax of the declaration; remove the number preceding 
the variable name. 


BADTARGET A reference in an assignment context is not valid for 
assignment. 


Error. The target of an assignment is a reference to a named constant, or to a variable with the 
READONLY or VALUE attribute. 


User Action. Correct either the reference or the declaration of the name. 


BADTEXTEND Invalid end of text. Check for unbalanced apostrophes or 
unbalanced comments. 


Error. The compiler reached the end of the input file while it was reading a character-string constant or a 
comment. 


User Action. Locate the unterminated comment or string constant and correct it. 


BADUNSPREF The argument of UNSPEC must be a reference to a scalar 
variable or a reference to an element of an array of scalar 
values. 


Error. The UNSPEC built-in function is used incorrectly. 
User Action. Correct the reference to UNSPEC. Its argument may not be a constant or a structure name. 


BADVALUSE An expected data-type value was not found. One of the 
values in this statement has a data type that cannot be 
converted to the type required by the context in which 
the value is used. 


Error. A noncomputational data type is specified when a computational data type is required, or vice 
versa. For example, this error occurs if the CHARACTER built-in function specifies a pointer or entry value 
for an argument. 


User Action. Verify that the variable in question is correctly declared. If it is, correct the statement so tha* 
it refers to a variable of the correct data type. 
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BLANKGIVEN An arithmetic constant must be separated from the following 
symbol by a delimiter. A blank delimiter has been 
supplied. 


Warning. This message indicates a syntax error in a constant, for example, an invalid character in a 
floating-point number or the omission of apostrophes around a bit-string constant. 


User Action. Correct the constant. 


BUGCHECK Compiler bug check during phase. 
Submit an SPR with a problem description. 


Fatal. An internal error occurred in the compiler. 


User Action. Gather as much information as possible about the conditions in effect when the error 
occurred and submit an SPR. 


CMPLXDOPE The dope vector required for the argument 
“name” is too complicated. 


Error. A structure parameter has so many members with asterisk (*) extents that the required dope vector 
cannot be represented in the compiler’s intermediate language. 


User Action. Simplify the parameters. 


CNDNAMEVAL A parenthesized name or value is not valid with 
the “condition-name” condition. 


Error. Only the I/O condition names and the VAXCONDITION condition name may specify values. 
User Action. Correct the ON condition name in the statement. 


COMPILERR Previous errors prevent continued compilation. 
Correct all errors and recompile. 


Fatal. The compiler cannot continue. 
User Action. Correct the errors indicated in the preceding messages. 


CONFLATTR Attributes declared for “name”’ conflict 
with factored attributes. 


Error. An attribute specified for a variable within a list of factored attributes conflicts with an attribute 
specified in the variable declaration. For example, this error occurs if a precision or extent is specified twice 
and the values do not match, as in: DECLARE (X CHAR(8),Y) CHAR(10); 


User Action. Determine which declaration of the attribute is valid and correct the statement. 


CONPREC The precision arguments of BINARY, DECIMAL, FIXED, FLOAT, and 
DIVIDE built-in functions must be decimal integer constants. 


Error. A nonconstant value is specified for the precision argument of one of the built-in functions listed. 


User Action. Correct the argument list for the built-in function in error so that it specifies a constant value 
for the precision argument. Replace the variable specified for the precision argument with a decimal integer 
constant. 


CONSTCOND A condition occurred while evaluating an 
expression with constant operands. 


Warning. The compiler evaluated an expression at compile time which resulted in the occurrence of a PL/I 
condition. The most common condition that occurs is FEXEDOVERFLOW. 


User Action. Try to determine what expression caused the condition. Look especially at subscripts, the 
second and third arguments of SUBSTR references, expressions for string sizes, and array bounds. When 
you locate the reference (you may want to use the debugger to help locate the reference), correct it. 
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User Action. Check that the reference is correctly spelled; if not, correct the spelling of the reference. If the 
variable is not declared, declare it with the appropriate attributes for its use. 


DIVIDE The divide operator was used with FIXED BINARY operands. 
The compiler transformed this to DIVIDE(x,y,31). 


Warning. In full ANSI PL/], the divide operator with FIXED BINARY operands usually yeilds a scaled 
result, that is, it has fractional digits. However, VAX-11 PL/I does not support scaled binary data. The 
compiler treated the division of fixed binary values as integer division. 


User Action. Rewrite the statement using the DIVIDE built-in function instead of the division operator. 


DUMMYARG A dummy argument has been created for argument 
because it does not exactly match the data-type parameter. 


Warning. The compiler converted the argument to the data type of the corresponding parameter, and 
placed the result in a dummy argument. It is passing a reference to the dummy argument rather than to the 
actual argument to the called procedure. 


User Action. If the conversion is acceptable, and if the argument will not modified in the called procedure, 
you need do nothing. You can enclose the argument in parentheses to suppress the message. However, if the 
argument must be passed by reference so that the called procecure may modify it, correct the declaration of 
the argument or the parameter descriptor or parameter list for the corresponding parameter. 


DUPDCL This statement contains a duplicate declaration of 
“name’’. 


Error. The same identifier is used in more than one declaration at the same level. 


User Action. Determine which declaration of the variable specifies the correct attributes, if they are 
different, and change the incorrect declaration. 


DUPLABL This statement contains a label prefix that has appeared 
on a previous statement in the same block. 


Error. Two labels in the same block specify the same user-specified identifier and constant subscript. 
User Action. Correct the identifier and/or the subscript and all references to it. 
DUPOPTN This statement contains duplicate options. 


Error. A statement contains more than one specification of the same option, for example the LIST option is 
specified more than once in a PUT statement. 


User Action. Determine which specification of the duplicated option is the correct one and delete the other 
from the statement. 


DUPSIGN “token” contains multiple sign symbols. 
Error. A picture specification contains more than one sign (+ or -) symbol. 
User Action. Correct the picture so that it contains only a single sign. 


EMPTYARG ‘name’ has been referenced with an argument list which 
is incompatible with its declaration. An empty argument list 
is required to satisfy the declaration. 


Error. A CALL statement or a function reference specifies an argument list for a procedure that has no 
parameters. 


User Action. Verify the arguments required for the procedure invocation. If the parameter descriptor or 
parameter list does not specify any parameters, the procedure invocation must not specify any arguments. 
Note whether the parameter descriptor list or parameter list is in error; if so, correct it. Otherwise, correct 
the procedure invocation. 
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FLTBPREC The precision specified for “name” exceeds 
the implementation’s limit of FLOAT BINARY(precision). 
The maximum precision of precision has been supplied. 


Warning. The compiler changed the precision of the floating-point variable. 


User Action. Correct the declaration of the variable so that it does not specify a precision greater than the 
system’s maximum. 


FLTDPREC The precision specified for “name” exceeds 
the implementation’s limit of FLOAT DECIMAL(precision). 
The maximum precision of precision has been supplied. 


Warning. The compiler changed the precision of the floating-point variable. 


User Action. Correct the declaration of the variable so that it does not specify a precision greater than the 
system’s maximum. 


IDENTSIZE An identifier contains more than 31 characters. 
Only the first 31 characters will be used. 


Warning. The compiler truncated a user-specified identifier that is longer than 31 characters. 
User Action. Shorten the identifier to 31 characters or fewer. 
IMPLBLTIN name has been implicitly declared as a built-in function. 


Warning. The undeclared name of a built-in function with no arguments has been used without an explicit 
empty argument list, for example DATE was specified instead of DATEK(). 


User Action. Declare the function or specify with the empty argument list. 


INCNESTLVL %INCLUDE statements cannot be nested more 
than 4 levels deep. 


Fatal. The compiler encountered a %INCLUDE statement when it was already at the maximum nesting 
level of INCLUDE files. 


User Action. If the LIST_INCLUDE option was not in effect when you compiled the program, recompile 
the program specifying /LIST and /ENABLE=(LIST_INCLUDE). Then, examine the listing to ascertain 
which INCLUDE file caused the error. Correct the logical nesting of the INCLUDE files and/or modules so 
that the nesting level is no greater than four. 


INCSYN Invalid syntax in %INCLUDE statement. The correct syntax 
is “%INCLUDE ‘file-spec ’;” or “%INCLUDE text-module-name;”’. 


Error. A “INCLUDE statement is incorrectly specified. 


User Action. Examine the “INCLUDE statement. If the INCLUDE file is in an individual file, the file 
specification must be enclosed in apostrophes. If the INCLUDE file is in a text library module, no apos- 
trophes must be specified and the module name must not contain any punctuation marks. 


INITCVT One of the initial values specified for “name” 
cannot be converted to the type of the variable. 


Error. An invalid value is specified in an INITIAL attribute. 


User Action. Compare the data type of the constants specified in the INITIAL attribute list with the 
attributes specified for the variable. Determine which has the appropriate data type and correct the other. 
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User Action. Correct the declaration of the parameter so that it does not specify a storage class attribute. A 
parameter occupies the storage of its corresponding argument at the timé of the invocation, and thus 
cannot be allocated storage in any other way. It also cannot be used as a label. 


INVSTARUSE ‘“name’’ is declared with an * extent but is not 
a parameter or a descriptor. 


Error. An asterisk is specified for the length of a character string or for the dimension of an array, and the 
string or array is not a parameter. 


User Action. Correct the declaration of the variable so that its extent is specified using a constant or a 
valid variable declaration. 


INVSUBLABL ‘“‘name’’ is a subscripted label prefix 
previously declared with a different data type or a 
different number of dimensions. 


Error. A label conflicts with the declaration of a variable. 


User Action. If the label prefix has the same identifier as a declared variable, change either the label or the 
variable and correct all references to them. 


ITERFACT If an iteration factor is used with a string constant, 
the constant must be enclosed in parentheses. 
This construction means “iteration‘‘ occurrences of the 
constant as opposed to concatenation. 


Warning. An iteration factor is specified for a string constant in an INITIAL attribute, but the iteration 
factor is not enclosed in parentheses. The compiler assumes that the factor is in parentheses. 


User Action. Place the iteration factor in parentheses, for example: INITIAL((5)( ‘strings °)). 


ITERVAL ‘token’ has been declared with a variable iteration 
factor. An iteration factor of one has been supplied. 


Error. A nonconstant iteration factor was used to initialize a static variable. Nonconstant iteration factors 
are valid only in the initialization of automatic variables. 


User Action. Specify a constant in the iteration factor. Or, declare the variable with the AUTOMATIC 
attribute. 


LIBERROR Error while reading library “library-name’’. 


Fatal. The compiler cannot read the indicated library. Either the file is not a library, or its format has been 
corrupted. 


User Action. Verify that the library file is specified correctly, and that it is a valid VAX/VMS text library. 
LIBLOOKUP ‘“‘module-name” was not found in any of the specified libraries. 


Fatal. The compiler failed to locate the indicated module in any library specified on the PLI command, in 
the library specified as PLISLIBRARY, if any, or in the default INCLUDE library. 


User Action. Check the PLI command line to verify that the library containing the specified INCLUDE 
text module was specified and that the name of the module was spelled correctly. If the library is a default 
user library, determine whether it has been assigned to the logical name PLISLIBRARY. 


LOCNEED “name’’ is a based variable referenced without a 
locator qualifier. 


Error. A variable is declared with the BASED attribute without a pointer variable and is referenced 
without a locator qualifier (->). 


User Action. Specify a pointer variable in the declaration of the variable, or specify the current pointer 
reference in the statement that caused the error. 
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NOLABL PROCEDURE, ENTRY, and FORMAT statements must have a label. 
Error. The indicated statement is not labeled. | 
User Action. Place a label on the statement that caused the error. 

NOLISTING No listing file produced. 

Informational. The compiler did not create a listing file. 


User Action. None. 


NOLOCNEED “name” is a nonbased variable referenced with 
a locator qualifier. 


Error. A locator-qualified reference is specified for a variable that does not have the BASED attribute. 


User Action. Remove the locator qualifier (->) from the reference. If you expected that the variable needed 
a locator qualifier, verify that the variable has the BASED attribute. 


NONCONEXTN “name” is declared with nonconstant extents but is 
not an automatic, based, or defined variable. 


Error. The indicated variable or descriptor for a character-string, bit-string, or array variable used a 
variable instead of a constant to define the extent. Variables are permitted for extents only for automatic, 
based, and defined variables. 


User Action. Correct the declaration of the variable. © 


NONCONINIT ‘‘name’”’ has been declared with a nonconstant initial 
value. Static variables must have constant initial values. 


i 
Error. A static variable is incorrectly initialized. 
User Action. Correct the declaration so that it uses only constant values in the INITIAL attribute. 
NORETVAL All RETURN statements in a function must return values. 


Error. A RETURN statement in a function does not specify a value. 


User Action. Specify a value on the RETURN statement, ensuring that the data type of the value matches 
the data type specified on the RETURNS option of the PROCEDURE statement. 


NOTARITH Implicit conversion. A nonarithmetic expression, expression, 
has been used in a context requiring an arithmetic value. 


Warning. A bit-string or character-string expression was used in a context where an arithmetic expression 
is required. The PL/I compiler has converted the expression to arithmetic. This situation may or may not 
constitute an error. 


User Action. To avoid this message in circumstances in which you want the compiler to convert the 
expression to the appropriate arithmetic data type, use the BINARY built-in function to convert a bit 
string or the BINARY, FIXED, DECIMAL, or FLOAT built-in function to convert a character string. You 
can also suppress the message by compiling the program with the /NOWARNINGS qualifier. 


NOTARRAY The first argurnent to a LBOUND, HBOUND, or DIM built-in 
function must be an array reference. 


Error. The argument list for one of the functions listed is incorrectly specified. 
User Action. Correct the argument list for the built-in function. 
NOTBASED The variable “name” is not a BASED variable. 
Error. The target variable specified in the ALLOCATE statement does not have the BASED attribute. 


User Action. Verify that the variable is specified correctly. If so, correct the variable’s declaration so that it 
specifies BASED. 
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User Action. Verify that the reference in the condition name is to a file constant or file variable that is’ 
declared correctly. 


NOTINT Implicit conversion. A noninteger expression, expression, 
has been used in a context requiring an integer value. 


Warning. A character-string, bit-string, or noninteger arithmetic expression is used in a context where an 
integer is required. The PL/I compiler has converted the expression to an integer. This situation may or 
may not constitute an error. 


User Action. To avoid this message in circumstances in which you want the compiler to convert the 
expression to an integer, use the BINARY built-in function to convert bit- or character-string expressions to 
an integer. You can use the FIXED built-in function to convert floating-point expressions or fixed-point 
decimal. expressions with a nonzero scale factor to integers. You can also suppress the message by compil- 
ing the program with the /NOWARNINGS qualifier. 


NOTINTBND A constant has been used as an array bound, but it is not an 
integer constant whose value is less than 2**29. If a 
constant is used as a bound, it must be a valid integer. 


Error. An invalid constant is specified for an array bound. 


User Action. Verify that the bound specified is within the valid range for array bounds and correct the 
declaration. Note that this error may occur when any parenthesized expression follows an identifier in a 
declaration. In this context, the message indicates that the statement syntax is in error and must be 
corrected. 


NOTINTCON An expected optionally signed integer was not found. 
Error. A nonconstant expression is specified in a context that requires an integer constant. 
User Action. Specify an integer constant. 


NOTINTVAL A noninteger value is specified as a VAXCONDITION 
value. 


Warning. A noninteger value is specified for the VAXCONDITION condition name. 


User Action. Specify an integer value in the ON, SIGNAL, or REVERT statement. 


NOTLOCATOR A value that is not a pointer or offset value has been 
used in a context requiring a locator value. 


Error. The reference specified as a locator qualifier is not a pointer or offset value. 


User Action. Correct the locator-qualified reference so that the item on the left of the locator qualifier (->) 
is a pointer or offset. 


NOTSCALAR An array or structure value has been used in a context 
that requires a scalar value. 


Error. An array or structure reference is specified in an invalid context, for example, as an operand of an 
arithmetic operation. 


User Action. Correct the statement so that it does not contain a reference to an aggregate. 


NOTSUBROUT The reference in a CALL statement is not 
a subroutine reference. 


Error. A CALL statement specifies the name of an entry that has the RETURNS attribute. 


User Action. If the invoked procedure is a function, correct the statement in error so that the procedure is 
invoked as a function reference. Otherwise, delete the RETURNS option from the PROCEDURE state- 
ment of the procedure so that it can be invoked by a CALL statement. 
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REQINIT An INITIAL attribute must be specified for “name’’. 


Warning. The indicated name is not specified with the INITIAL attribute. This error occurs for names 
declared with the READONLY or VALUE attributes. Since names with these attributes cannot be modi- 
fied, their values are unpredictable if they are not initialized. 


User Action. Specify the INITIAL attribute to give the name a value. 


RETANY A returns descriptor must not specify ANY 
as its data type. 


Error. The ANY attribute is specified in a returns descriptor. 


User Action. Correct the returns descriptor so that it specifies data type attributes for the return value. 
The ANY attribute is valid only for parameter descriptors for non-PL/I procedures. 


RETLENGTH A RETURNS attribute must not specify an array, structure, 
or area. 


Error. The data type specified in a returns descriptor is an aggregate or area. 


User Action. Ensure that the returns descriptor in the RETURNS option of the PROCEDURE statement 
for the function does not specify an aggregate or area value. 


RETSTAR Invalid *-extent in a RETURNS attribute. 


Error. An asterisk is specified for an extent or precision in a RETURNS attribute. The only valid use of an 
asterisk in a RETURNS attribute is RETURNS (CHARACTER(*)). 


User Action. Specify a value in the RETURNS attribute. 
RETURNON A RETURN statement is not allowed in an ON-unit. 
Error. A RETURN statement is specified within a begin block specified for an ON-unit. 
User Action. To exit from the program, use a nonlocal GOTO within the ON-unit. 
RETVAL A RETURN statement in a subroutine cannot return a value. 
Error. A RETURN statement in a subroutine specifies a value. 


User Action. Ascertain whether the indicated procedure is to be invoked as a subroutine or as a function. If 
it is a subroutine, remove the return value from the RETURN statement. If it is a function, specify the 
RETURNS option on its PROCEDURE statement. 


RETVALCVT Implicit conversion of the return value, 
expression, to the function type data-type. 


Warning. The data type specified in a RETURN statement does not match the data type given in the 
corresponding returns descriptor, and the compiler has performed an implicit conversion of the value to the 
specified data type. In the case of a procedure with multiple entry points, this message may be issued once 
for each occurrence of a RETURN statement that requires an implied conversion. 


User Action. If the conversion is desirable, either use a specific conversion built-in function to return the 
value, as in RETURN(CHAR(n)). Either correct the RETURNS option on the PROCEDURE or ENTRY 
statement that is in error, or correct the value specified in the RETURN statement. 
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STRDEPTH The depth of nesting of a structure exceeds the 
implementation’s limit of 16. 


Fatal. A structure contains too many levels. 


User Action. Correct the declaration of the structure. If necessary, modify the structure so that it has no 
more than 16 levels. 


STREFCNT A structure-qualified reference contains more than 15 
qualifying names. 


Error. A reference in the form namel.name2.name3... contains more than 15 names. 


User Action. Examine the structure-qualified reference and compare it with the declaration of the struc- 
ture, to ensure that each qualifying name is specified correctly. 


STRGTOOBIG The length of a name or constant exceeds the 
implementation’s limit of 1000 characters. 
Check to see if all string constants are properly delimited 
with © and that any contained ‘s occur in pairs. 
Also check for unbalanced /* */. 


Fatal. The compiler read more than 1000 characters following the occurrence of an open apostrophe () or 
comment (/*). 


User Action. Locate the beginning of the unterminated string or comment, and terminate it at the 
appropriate location. 


STRINGBIF The argument of the STRING built-in function must be a 
variable that is suitable for use in string overlay 
defining. It must contain only bit or only character data 
and must not be VARYING or ALIGNED or be an unconnected 
array. 


Error. The STRING built-in function is used incorrectly. 


User Action. Verify that the correct argument is specified for the STRING built-in function. If the 
argument seems correct, be sure that its declaration does not violate any of the rules given in the message. 


SUBRANGE The integer value “‘token’’ does not lie in 
the range minimum : maximum. 


Error. The PL/I compiler detected a reference to an array in which a subscript is not within the declared 
bounds of the array or an argument in a SUBSTR built-in function that references a position that is not 
within the extent of the target string. This message is issued only if /CHECK was specified on the PLI 
command to compile the program. 


User Action. Correct the reference to the array. 
SUBROUT The subroutine name has been called as a function. 
Error. The statement contains a reference to a procedure that does not have the RETURNS attribute. 


User Action. If the invoked procedure is a subroutine, correct the statement in error so that the procedure 
is invoked with a CALL statement. Otherwise, delete the RETURNS attribute from the PROCEDURE 
statement of the procedure so that it can be invoked by a function reference. 


SYMTABOVFL The total number of symbol table pages exceeds 
the implementation’s limit. Reduce the 
number and size of names, constants, extent expressions, 
and argument or returns descriptors. 


Fatal. The program is too complex. 


User Action. Simplify the program. 


PL/I Messages B-23 


TOOMANYERR The total number of errors exceeds the implementation’s 
limit of 100. 


Fatal. The compiler cannot continue. 


User Action. Correct the errors indicated by the preceding messages. 


TOOMANYOPS More than 253 operands have been used with an operator, 
function, or call. 


Error. An expression contains more than 253 operands. 
User Action. Simplify the statement in error. 
TOOMANYSUB ‘name’ has been referenced with too many subscripts. 


Error. The number of subscripts in the reference to an array element exceeds the number of dimensions of 
the array. 


User Action. Examine the declaration of the array to determine the number of subscripts required, 
determine the subscript(s) in excess, and correct the statement. 


TOOMANYVAL Excess initial values have been specified for “name’’. 


Warning. An INITIAL list for an array declaration specifies more constant values than array elements. Or 
multiple values were specified for a scalar constant. A list of values is valid only in an array declaration. 
The declaration DCL (A,B) ... INIT(1,2) initializes both A and B to 1. The second value specified is 
ignored. 


User Action. Delete the excess values. 


TOPOLOGY An assignment target, parameter descriptor, or returns’ 
descriptor is not an array or structure of the proper shape 
to receive the array or structure value being assigned to it. 


Error. An array or structure is being assigned or passed to an array or structure with a different dimension, 
data type, or arrangement. 


User Action. Compare the declaration of the array or structure that is specified as an argument or as a 
source expression with the corresponding parameter or target expression. Determine which declaration is 
correct and modify the incorrect specification. 


UABORT Compilation terminated by user. 
Fatal. You interrupted the compilation with and the compiler has terminated. 
User Action. None. 


UNDCLBASE ‘name’ is undeclared and has been used in an 
ALLOCATE statement as the name of a based variable. 


Error. The target variable in the ALLOCATE statement is a name that is not declared. 


User Action. Verify that the variable is specified correctly. If so, declare it with the BASED attribute. 


UNDCLPARM “name” is an undeclared parameter. It has been 
declared in its containing block and will acquire default 
attributes. 


Warning. A name specified in a parameter list is not declared with data type attributes. The compiler gave 
the parameter the attributes FIXED BINARY(81). 


User Action. Declare the parameter with the appropriate data type attributes. 
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UNRSTREF A structure-qualified reference to “name’’ cannot be 
resolved to any declaration known to this block. 


Error. A reference in the form namel.name2.name3... cannot be resolved. 


User Action. Examine the structure-qualified reference in the statement that caused the error. Verify that 
the structure member that is referenced is a part of the specified structure. Correct the reference so that it 
refers to the correct structure or to the correct member. 


UPPRGTRLOW One of the bounds declared for “array-name’’ is invalid 
because the lower bound is greater than the upper bound. 


Error. An array is incorrectly declared. 


User Action. Correct the declaration of the array variable in error so that all bounds are valid. In the 
declaration of the a bound x:y, the value of x must be numerically less than the value of y. 


VALSIZE The size or precision of ‘““name”’ 
is incompatible with the VALUE attribute. 


Error. A parameter descriptor or variable declared with the VALUE attribute specifies a fixed binary value 
with a precision not equal to 31 or a bit-string value with a length not equal to 32. 


User Action. Correct the declaration so that it specifies a variable that requires 32 bits or less of storage. 


VALTYPE The data type of “name” is incompatible with 
the VALUE attribute. 


Error. The VALUE attribute is specified for a variable that does not have either the FIXED BINARY or 
BIT(382) ALIGNED attribute. 


User Action. Correct the declaration. 


VARYING ‘‘name”’ has been declared with the VARYING attribute. 
Only CHARACTER variables may be declared VARYING. 


Error. The VARYING attribute is specified for a variable to which it cannot be applied. 
User Action. Correct the declaration so that it does not specify VARYING. 


VARYSCALE The scale factor, q, specified for “name” is not 
in the range 0<q<p, where p is the variable’s precision. 
The scale factor has been set to zero. 


Warning. A scale is specified for a variable that is not in its declared range. 
User Action. Specify a scale factor in the allowed range. 


WHATBIF “name’’ is not a built-in function or procedure 
known to this implementation. If this is an external entry, 
it must be declared by a DECLARE statement with an ENTRY 
attribute. 


Error. A reference to a procedure cannot be resolved. 


User Action. Verify that the variable referenced in the statement is a valid subroutine or function. If it is 
an external function, declare it with the ENTRY attribute. 


ZEROSCALE “name” has been declared with a nonzero scale factor. 
A zero scale factor has been supplied. 


Warning. A variable is declared FIXED (p,q) or FIXED BINARY (p,q). 


User Action. Either specify the DECIMAL attribute or delete the scale factor, q, from the declaration. 
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For other types of print files, you may want to take special action for the ENDPAGE condition and code an 
ON-unit to perform the action. 


ERROR PL/I ERROR condition 


Fatal. This message is displayed whenever the ERROR condition is signaled and not handled within the 
procedure. 


User Action. This message is usually followed by additional messages that indicate the specific error that 
occurred, Examine these messages to determine the corrective action required. 


FINISH PL/I Program FINISH condition 


Success. This message is displayed when the FINISH condition is signaled and the program has no ON- 
unit for the FINISH condition. 


User Action. In many cases, this message is displayed when you have interrupted a program with or 
and executed another program or a DCL command. In these cases, no action is required. Otherwise, 
you may want to write an ON-unit to respond specifically to the FINISH condition in a program. For a 
description of image exit, and the circumstances under which PL/I signals the FINISH condition, see 
Section 4.1.1, “Image Exit.” 


FIXOVF PL/I FIXEDOVERFLOW condition. 


Fatal. This message is displayed when the FIXEDOVERFLOW condition occurs or is signaled and no ON- 
unit exists for FIXEDOVERFLOW. 


User Action. Determine the variable whose value overflowed and give it a larger precision, or verify that 
the program logic is correct and is not trying to assign a value larger than it should to the variable. If the 
condition is.expected, code an ON-unit in your program that handles this condition. 


KEY PL/I KEY condition on file ‘file-spec’ 


Fatal. This message is followed by one or more messages that indicate the specific error that occurred while 
processing the key on the given file. 


User Action. Determine the specific error that occurred by examining the accompanying RMS message. 
Verify in your program that the correct key value was specified in the I/O statement, that the data type of 
the key value can be converted to the data type of the given key, and so on. Also determine whether the file 
to which the I/O was attempted is the correct file. If appropriate, write an ON-unit to handle the KEY 
condition. 


UNDFILE PL/I UNDEFINEDFILE condition on file ‘file-spec’ 


Fatal. This message is followed by one or more messages that indicate the specific error that occurred 
opening the given file. 


User Action. Determine the corrective action from the accompanying messages. Verify the file specifica- 
tion in the FILENAME message to determine whether the correct defaults are being applied, whether all 
required logical name assignments are in effect, and so on. 


VAXCOND User-defined condition, condition-value 


Warning. This message is displayed when VAXCONDITION is signaled and no ON-unit exists to handle 
the specific numeric condition value. 


User Action. Verify that the condition value specified in the SIGNAL statement matches the condition 
value in a corresponding ON-unit. Correct the source program and recompile. 


ZERODIV PL/I ZERODIVIDE condition. 


Fatal. This message is displayed when the ZERODIVIDE condition occurs; that is, the divisor in a division 
operation has a value of zero. This message is displayed when the condition is not handled by an ON-unit 
within the PL/I program. 


User Action. Determine the statement that caused the error and correct the program logic, if possible. If 
practical, code an ON-unit to detect the condition and take appropriate action. 
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CONFIXLEN FIXED_LENGTH RECORDS conflicts with other attributes or options. 


Informational. The file’s attribute list contains the FIXED_LENGTH__RECORDS option and an option 
that conflicts with it. 


User Action. Consult the option description(s) in Chapter 6 to determine the options in conflict and correct 
the program. 


CONPRINTCR CARRIAGE__RETURN__FORMAT conflicts with PRINT attribute. 


Informational. A PL/I file with the PRINT attribute has variable with fixed-length control records; 
the carriage control information is provided by PL/I. The CARRIAGE__RETURN__FORMAT option of 
ENVIRONMENT cannot be specified for it. 


User Action. Determine whether the file is to be a PL/I PRINT file or a file with VAX/VMS carriage return 
format and correct the file’s attribute list. 


CONPRTFRM PRINTER FORMAT conflicts with other attributes or options. 


Informational. The ENVIRONMENT option PRINTER_FORMAT conflicts with the CARRIAGE_ 
RETURN__FORMAT option and with the PRINT and STREAM file description attributes. 


User Action. Correct the file’s attribute list. 
CREINDEX Attempting to create an indexed file. Use RMS DEFINE. 


Informational. A file was opened with the OUTPUT attribute and with the ENVIRONMENT option 
INDEXED. You cannot create an indexed sequential file in a PL/I program. Indexed files can only be 
opened for UPDATE or INPUT. 


User Action. Use the RMS-11 utility program DEFINE to create the file. Correct the program to open the 
file with the UPDATE attribute and write records to it. 


CVTPICERR Error in picture conversion. . 

Informational. A value could not be edited as specified by the corresponding picture. 

User Action. If the value is negative, be sure that the picture includes one of the sign characters. 
ENDSTRING End of string encountered during GET STRING or PUT STRING. 


Informational. A GET STRING statement attempted to read past the end of the source string variable; or, 
a PUT STRING statement attempted to write past the end of the target string variable. This error occurs 
most frequently when a LIST option is specified on a GET STRING statement and the target string does 
not have either a trailing blank or a comma. 


User Action. Verify the length of the target or source string variable, the data types specified in the GET or 
PUT list, correct the program, and recompile. 


ENVPARM PL/I compiler/run-time error. Please submit an SPR. 
Informational. An error occurred in the execution of the PL/I compiler or a run-time module. 


User Action. Gather as much information as possible about the circumstances under which the error 
occurred and submit an SPR report. 


FILEIDENT PL/I compiler/run time error. Please submit an SPR. 
Informational. An error occurred in the execution of the PL/I compiler or a run-time module. 


User Action. Gather as much information as possible about the circumstances under which the error 
occurred and submit an SPR report. 


FILENAME File name: ‘file-spec ’ 


Informational. This message specifies the VAX/VMS file specification of the file to which input/output 
was attempted. 


User Action. Examine this informational message to determine the full specification of the VAX/VMS file 
on which the input/output that failed was attempted. From this name, you can verify whether the file was 
correctly specified in the TITLE option, whether the correct logical name assignments exist, whether the 
correct defaults are being applied, and so on. 
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INVFMTPARM Invalid format parameter specified. 


Informational. A value specified for a format item was not a positive integer; or, the value was not in the 
valid range for the given format item. For example, this error occurs if a negative number is specified for the 
A or B format item, or if a value greater than 31 is specified for the F format item. 


User Action. Correct the value specified for the format item in the source program and recompile. 
INVFORGKEY Invalid file organization for KEYED access. 


Informational. The KEYED attribute was specified for a file that cannot be accessed by key, for example, 
a magnetic tape file. 


User Action. Verify that the correct file is being opened by checking the TITLE and DEFAULT__FILE__ 
NAME options, if any, logical name assignments, and file specification defaults. If the file is the expected 
file, correct the attribute list so that it does not specify the KEYED attribute. 


INVFORMAT PL/I compiler/run-time error. Please submit an SPR. 
Informational. An error occurred in the execution of the PL/I compiler or a run-time module. 


User Action. Gather as much information as possible about the circumstances under which the error 
occurred and submit an SPR report. 


INVFXCSIZ Invalid FIXED_-CONTROL_SIZE specified. 


Informational. The value specified in the FFXED__CONTROL__SIZE ENVIRONMENT option is not in 
the range of 0 through 255. 


User Action. Verify that the expression in the FIXED_-CONTROL_SIZE option is correctly specified or 
that it refers to the correct variable. Or, choose a fixed-control size that is within the valid range. Correct 
and recompile the program. 


INVINDNUM Invalid INDEX_-NUMBER specified. 


Informational. The value specified for the INDEX_.NUMBER option does not have a corresponding 
index in the indexed sequential file. 


User Action. Verify that the expression specified in the option is correct or that it refers to the correct 
variable. Or, specify an index number that is in the proper range, ensuring that the indexed sequential file 
was defined with the correct number of index keys. Correct and recompile the program. 


INVMAXREC Invalid MAXIMUM__RECORD_ SIZE specified 


Error. The value specified for the MAXIMUM__RECORD__SIZE option of ENVIRONMENT is not in 
the range of 0 through 32767. 


User Action. Correct the value so that it is not larger than 32767. 
INVMLTBLK Invalid MULTIBLOCK__COUNT specified. 


Informational. The value specified in the MULTIBLOCK__COUNT count of the ENVIRONMENT op- 
tion is not in the range of 0 through 127, or is not a valid integer expression. 


User Action. Verify that the expression in the MULTIBLOCK__COUNT option is correct, or that the 
correct variable reference is specified. Correct and recompile the program. 


INVMLTBUF Invalid MULTIBUFFER__COUNT specified. 


Informational. The value specified in the MULTIBUFFER__COUNT count of the ENVIRONMENT 
option is not in the range of -128 through 127, or is not a valid integer expression. 


User Action. Verify that the expression in the MULTIBUFFER__COUNT option is correct, or that the 
correct variable reference is specified. Correct and recompile the program. 
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LINESIZE Invalid LINESIZE specified. 


Informational. The value specified in the LINESIZE option exceeds the implementation’s limit of 32,767. 
Or, the value is not a positive integer value. _ 


User Action. Correct the LINESIZE option and recompile the program. 
NOCURREC No current record. 


Informational. A DELETE or REWRITE statement was specified for a file opened with the UPDATE 
attribute, but the KEY option was not specified. These statements may omit the KEY option only if the 
“current record” contains a valid value. 


User Action. Correct the statement in the source program and recompile. 
NOFROM No FROM specified or buffer not allocated. 


Informational. A REWRITE statement was specified without the FROM option. The REWRITE state- 
ment is valid without the FROM option only if a previous READ statement on the file specified the SET 
option to allocate a buffer and set a pointer to the record read. 


User Action. Correct the previous READ statement for the file so that is specifies the SET option or 
correct the REWRITE statement so that is specifies the FROM option. 


NOKEY No KEY or KEYFROM specified. 
Informational. A keyed I/O statement must specify a KEY or KEYFROM option. 


User Action. Correct the statement and recompile the program. If you are attempting sequential access to 
a file, verify that you have also specified SEQUENTIAL in the file’s attribute list. 


NOSHARE SHARED__READ or SHARED_WRITE conflicts with NO_SHARE. 


Informational. The ENVIRONMENT options SHARED__READ and SHARED__WRITE permit read or 
write sharing on a file, but the NO_'SHARE option prohibits all sharing. 


User Action. Determine whether the file is to be accessed for sharing. If not, delete the option in error. If it 
is to be shared, delete the NO__'SHARE option. Recompile the program. 


NOTINDEXED Requested operation requires an INDEXED file. 


Informational. A keyed I/O statement specifies an operation that is valid only for a file with indexed 
sequential file organization. 


User Action. Determine from the information in the FILENAME message whether the operation was 
requested to the appropriate file. If the file is correctly specified but is not an indexed file, it may not have 
been properly created. 


NOTINPUT Attempting to GET from an OUTPUT or UPDATE file. 


Informational. A GET statement is not valid on a file that is opened with the OUTPUT or UPDATE 
attributes. 


User Action. Correct the file’s attribute list and recompile. 
NOTKEYD Not a KEYED file. 


Informational. A KEY or KEYFROM option was specified in a record I/O statement for a file that does not 
have the KEYED attribute. 


User Action. Verify that the file is a keyed file, and if it is, correct the DECLARE or OPEN statement for 
the file so that it specifies the KEYED attribute. 


NOTOUT Attempting to PUT to an INPUT or UPDATE file. 


Informational. The PUT statement is not valid for files that are opened with the INPUT or UPDATE 
attribute. 


User Action. Correct the file’s attribute list and recompile. 
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PROMPTOBIG PROMPT option too long. Must be < 254 characters. 


Informational. The string specified in the PROMPT option of the GET statements exceeds the maximum 
length of 253 characters. 


User Action. Shorten the prompting string and recompile. 
READOP PL/I compiler/run-time error. Please submit an SPR. 
Informational. An error occurred in the execution of the PL/I compiler or a run-time module. 


User Action. Gather as much information as possible about the circumstances under which the error 
occurred and submit an SPR report. 


READOUT Attempting to READ from an OUTPUT file. 


Informational. A file that is opened with the OUTPUT attribute cannot be accessed with a READ 
statement. If you are attempting to read a file that was just written, you must first close the file and reopen 
it with the INPUT attribute. 


User Action. Correct the source program and recompile. 
RECID File not open for RECORD__ID__ACCESS. 


Informational. The RECORD_ID__TO and RECORD__ID__FROM options are valid only if the file’s 
ENVIRONMENT option list specified RECORD_ID__ACCESS. 


User Action. Correct the ENVIRONMENT option list and recompile the program. 
RECIDKEY RECORD_ID_FROM conflicts with KEYED or KEYFROM. 


Informational. A record I/O statement may not specify the KEY or KEYFROM option and the 
RECORD__ID__FROM option at the same time. 


User Action. Correct the statement and recompile the program: 
RECORD Record length does not match target length. 


Informational. A fixed-length character string buffer is not the same length as a record being read by a 
READ statement. 


User Action. Verify that the variable to which you are transferring data is the correct length for the records 
in the file. Correct the source program and recompile. 


RECURSIO Illegal recursive I/O attempted. 


Informational. An input or output operation was attempted to a file on which another J/O operation is 
currently being performed. 


User Action. Correct the logic of the program and recompile. 
STROVFL Stream item too big. Must be less than 1000 characters. 
Informational. The run-time system cannot process a string longer than 1000 characters. 


User Action. Correct the input or output field width and recompile the program. If necessary, use more 
than one stream I/O statement. 


SUBRANGE Subscript range check error. 


Error. The compiler detected a value that is beyond the range specified for a variable. This message is 
issued only if the procedure containing the reference was compiled with the /CHECK qualifier. 


User Action. Correct the reference. 
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SUBSTR2 Operand two of a SUBSTR is out of range. 


Error. The second operand in a reference to a SUBSTR built-in function or pseudovariable is beyond the 
range of the string. This message is issued only if the procedure containing this reference was compiled with 
the /CHECK qualifier. 


User Action. Correct the reference. 
SUBSTR3 Operand three of a SUBSTR is out of range. 


Error. The third operand in a reference to a SUBSTR built-in function or pseudovariable is beyond the 
range of the string. This message is issued only if the procedure containing this reference was compiled with 
the /CHECK qualifier. 


User Action. Correct the reference. 
TITLE Invalid TITLE specified. 


Informational. The size of the character-string expression specified in the TITLE option exceeds the 
maximum size of 128 bytes. . 


User Action. Select a smaller file title and correct the program. 
VIRMEMDEAL PL/I compiler/run-time error. Please submit an SPR. 
Informational. An error occurred in the execution of the PL/I compiler or a run-time module. 


User Action. Gather as much information as possible about the circumstances under which the error 
occurred and submit an SPR report. 


WRITEIN Attempting to WRITE to an INPUT file. 


Informational. A file that is opened with the INPUT attribute cannot’ be accessed with a WRITE state- 
ment. If you are attempting to write a file that was just read, you must first close the file and reopen it 
either with the UDPATE attribute or with the OUTPUT attribute and ENVIRONMENT(APPEND). 


User Action. Correct the source program and recompile. 


PL/I Messages B-39 


Appendix C 
Correspondence of PL/I and RMS 


Table C-1 lists the VAX-11 PL/I ENVIRONMENT options and gives the 
VAX-11 RMS macro, field, or bit setting, as appropriate, that corresponds to 
each. 


For detailed descriptions of the RMS fields, see the VAX-11 Record Manage- 
ment Services (RMS) Reference Manual. 


Table C-1: RMS Fields for PL/I ENVIRONMENT Options 


APPEND 


BATCH 
BLOCK__BOUNDARY__FORMAT 
BLOCK_IO 

BLOCK_SIZE 

BUCKET_SIZE 
CARRIAGE__RETURN__FORMAT 
CONTIGUOUS 
CONTIGUOUS__BEST__TRY 
CREATION__DATE 
CURRENT__POSITION 
DEFAULT_FILE_NAME 
DEFERRED__WRITE 

DELETE 

EXPIRATION__DATE 
EXTENSION__SIZE 





$RAB ROP=EOF 
$FAB FOP=CIF,- 
“MXV, NEF, “SUP 


$FAB FOP=SCF 
$FAB RAT=BLK 
$FAB FAC=BIO 
$FAB BLS 

$FAB BKS 
$FAB RAT=CR 
$FAB FOP=CTG 
$FAB FOP=CBT 
$XABDAT CDT 
$FAB FOP=POS 
$FAB DNM 
$FAB FOP=DFW 
$FAB FOP=DLT 
$XABDAT EDT 
$FAB DEQ 


(Continued on next page) 


Table C-1 (Cont.): RMS Fields for PL/I ENVIRONMENT Options 


TEMPORARY $FAB FOP=TMP 
TRUNCATE $FAB FOP=TEF 


WORLD__PROTECTION $XABPRO PRO 
WRITE__BEHIND $RAB ROP=WBH 
WRITE_CHECK . $FAB FOP=WCK 
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Appendix D 
ASCII Character Set 


ASCII Character Set 


ASCII 
Decimal 
Number Character Meaning Character 
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Null 

Start of heading 
Start of text 

End of text 

End of transmission 
Enquiry 
Acknowledgement 
Bell 

Backspace 
Horizontal tab 
Line feed 

Vertical tab 

Form feed 
Carriage return 
Shift out 

Shift in 

Data link escape 
Device control | 
Device contro] 2 
Device control 3 
Device control 4 
Negative acknowledgement 
Synchronous idle 
End of transmission block 
Cancel 

End of medium 
Substitute 

Escape 

File separator 
Group separator 
Record separator 
Unit separator 
Space or blank 
Exclamation mark 
Quotation mark 
Number sign 
Doilar sign 
Percent sign 
Ampersand 
Apostrophe 
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Left parenthesis 
Right parenthesis 
Asterisk 

Plus sign 

Comma 

Minus sign or hyphen 
Period or decimal point 
Slash 

Zero 

One 

Two 

Three 

Four 

Five 

Six 

Seven 

Eight 

Nine 

Colon 

Semicolon 

Left angle bracket 
Equal sign | 

Right angle bracket 
Question mark 

At sign 

Upper case A 
Upper case B 
Upper case C 
Upper case D 
Upper case E 
Upper case F 
Upper case G 
Upper case H 
Upper case I 
Upper case J 
Upper case K 
Upper case L 
Upper case M 
Upper case N 
Upper case O 
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Index 


$ACCDEF, 19-5 
Access modes, 9-2 
block I/O, 9-4 
random by key, 9-3 
record identification, 9-4 
relative record number, 9-3 
sequential, 9-3 
Access privileges, 13-2 
ADDR built-in function, 15-5 
pass pointer value, 14-7 
ALIGNED attribute 
bit-string arguments, 19-10 
ALLOCATE command, 1-9, 5-3, 10-2 
Allocation 
device, 10-5 
determine status, 8-6 
disk file space 
extend, 8-7 
set default quantity, 6-20 
specify size, 6-22 
storage in area, 18-5 to 18-6 
Alternate keys, 12-1 
access file using, 7-1, 7-7 
access records by, 12-11 
define, 12-6 
specify numbers, 12-8 
ANSI magnetic tape labels, 10-2 
ANY attribute, 14-4, 14-6 to 14-7, 19-24 
examples, 19-10 
used with VALUE, 14-5 
ANYCONDITION condition 
errors, B-28 . 
ANYCONDITION ON-unit, 17-7 
called during unwind, 17-15 
effect of nonlocal GOTO, 17-16 
located in search for ON-units, 
17-12 to 17-13 
STOP statement in, 17-15 
AP (Argument Pointer), 14-1 to 14-2 
APPEND (ENVIRONMENT option), 6-5, 
6-10, 10-3, C-1 
determine if set, 8-3 
example, 10-1 
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Area, 18-5 
allocate storage in, 18-5 to 18-6, 18-10 
free storage, 18-7, 18-12 to 18-13 
initialize, 18-5, 18-10 to 18-11 
longword reserved to DIGITAL, 
18-5, 18-10 
pass as argument, 18-8 
storage control, 18-6 to 18-13 
AREA attribute, 18-5 
Argument list, 14-2 to 14-3 
meaning of zeros, 14-13 
passed to ON-unit, 17-4 
variable-length, 14-12 
Argument pointer, 14-1 to 14-2 
Arguments 
default values, 14-13 
dummy, 14-4 
for AST routines, 19-20 
for system services, 19-2 to 19-3 
main procedure 
LIB$GET_FOREIGN, 4-10 
logical names, 4-12 
optional, 14-13 
pass by descriptor, 14-8 
pass by immediate value, 14-3 to 14-4 
pass by reference, 14-5 to 14-6 
pass to main procedure, 4-9 
passed to ON-unit display, 17-6 
passing conventions, 14-2 
specifying pointer values, 14-7 
Array descriptor, 14-8 
Arrays 
bound checking, 2-3 
pass as arguments, 14-5 to 14-6, 14-8 
to FORTRAN procedures, 14-6 
‘pass by descriptor, 14-9 
ASCII character set, D-1 
ASCII data (in stream files), 9-7 
Assembly language code 
print in listing file, 2-5 
ASSIGN command, 1-8 
Assign I/O Channel system service, 19-12 
AST routines 
considerations, 19-18 to 19-20 
pass parameters, 19-18 


Cell (in relative file), 11-1 
calculate size, 6-28 
relationship to record number, 9-2 
Channel number 
assign, 19-18 
mailbox, 19-10, 20-3 
assign, 19-12 
deassign, 20-3 
specify, 20-6 
specify as argument, 19-3 
Character set, ASCII, D-1 
Character strings 
arguments to ENVIRONMENT options, 
6-2 
as procedure arguments 
for system services, 19-3 
pass by descriptor, 14-9, 19-2 
- varying-length, 14-10 
constants 
as arguments, 19-8 
descriptors, 14-10 
user-coded, 14-10 
in stream files, 9-7 
keys in indexed files, 12-8 
reading and writing 
fixed-length, 9-5 
varying-length, 6-41, 9-6 
/CHECK qualifier, 2-3 
$CHFDEF 
example, 17-6 
fields defined in, 17-5 
CLOSE statement 
deassign mailbox channel, 20-3 
destroy logical network link, 21-3 
specify ENVIRONMENT options, 6-1 
$CODE program section, 18-2 
Colon 
in DEFAULT_FILE_NAME option, 5-7 
in TITLE option, 5-2 
Column number, determine current, 8-5 
COM file type, 4-7 
Command procedures, 4-7 
submit to batch queue, 6-10. 
used for network I/O, 21-4 
Commands 
hints for entering, 1-3 
maintaining files, 1-9 
pass data to a program, 4-9 
program development, 1-1 
Commas in argument list, 14-13 
omit for SORT, 22-1 
COMMON block, 15-2, 18-3 


Compiler 
control optimization, 2-6 
diagnostic messages, B-1 to B-27 
format, 2-10 
functions, 2-1 
input and output files, 2-7 
listing, 2-5, A-1 
listing options, 2-4 
options, 2-3 
stop, 2-11 
Concatenated input files, 2-9 
Condition handler, 17-1 
argument list, 17-4 
catch all conditions, 17-7 
compared to ON-unit, 17-1 
courses of action, 17-9 
default, 17-12 
LIBS$ESTABLISH, 17-2 
Condition handling, 17-1 to 17-14 
Condition values, 17-3 
bits defined in, 16-2 
file errors, 5-10 
user-defined, 17-8 to 17-9 
Conditions, 17-1 
CTRL/C, 19-18 to 19-19 
effect of handling, 17-9 
image exit, 4-3 
multiple active, 17-14 
resignaling, 17-9 to 17-10 
run-time, 4-2 
unwinding the call stack, 17-10 
CONTIGUOUS (ENVIRONMENT option), 
5-12, 6-5, 6-15, C-1 
determine if set, 8-3 
CONTIGUOUS_BEST__TRY 
(ENVIRONMENT option), 5-12, 6-5, 
6-16, C-1 
determine if set, 8-3 
CONTINUE command, 4-5 
Control bits (in status value), 16-2 
COPY command, 1-4, 1-9 
Copying PL/I source text, 2-12 
CREATE command, 1-9 
CREATE/DIRECTORY command, 1-9 
CREATION__DATE (ENVIRONMENT 
option), 6-5, 6-16, C-1 
example, 19-14 
Creation date of file 
determine, 8-3 
specify, 6-16 
example, 19-14 
/CROSS__REFERENCE qualifier, 2-4, A-6 
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Device independence, 1-7 
ENVIRONMENT options, 6-3 
DIRECT attribute, 9-2 
determine if file has, 8-5 
Directory 
changing default, 1-6 
default, 5-7 
SYS$LIBRARY, 2-17, 3-11 
DIRECTORY command, 1-9 
Directory specifications, rules, 1-5 
Disk files 
allocate contiguous, 6-15 
block I/O, 6-12 
extend allocation, 8-7 
Disk space, conserve, 6-46 
Display 
file information, 8-1 
logical names, 1-8 
DISPLAY built-in subroutine, 8-1 to 8-7 
device information, 8-6 to 8-7 
ENVIRONMENT information, 8-3 
file attribute information, 8-5 
Dope vector, 14-8 
Double-precision floating-point, 2-5 
Dummy arguments, 14-3 
for by-descriptor arguments, 14-12 
for by-reference arguments, 14-6 to 14-7 
for by-value arguments, 14-4 
Duplicate keys, 12-9 
test for errors, 12-13 
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EDIT command, 1-2, 1-9 
/ENABLE qualifier, 2-4, A-1 
END statement in main procedure, 4-1 
End-of-file 

in block I/O, 6-12 

indicated by SORT, 22-8 

meaning in mailbox I/O, 20-3 to 20-4 

meaning in network communication, 

21-3 

stream files, call REWIND, 8-9 

truncate file at logical, 6-46 
End-of-line delimiter for stream input, 6-25 
End-of-tape on volume, 10-5 
End-of-volume switching, 10-4 
ENDFILE condition, 5-9 

errors, B-28 

mailbox I/O, 20-3, 20-5 

network I/O, 21-5 

rewind stream file, 8-9 

signal value, 17-3 


ENDPAGE condition, 5-9 
action by default handler, 17-13 
errors, B-28 
signal value, 17-3 
ENTRY attribute 
declare non-PL/I procedures, 14-4 
OPTIONS (VARIABLE), 14-12 
Entry name, pass as procedure argument, 
14-4 
Entry point, 2-1 
as global symbol, 3-1 
main, 3-3, 4-1 
ENVIRONMENT options, 6-1 to 6-48 
file sharing, 13-5 
for input/output optimization, 5-12 
obtain information, 8-2 to 8-3 
specify arguments, 6-2 
specifying, 6-1 
summary, 6-4 to 6-9 
see also entries for individual options 
ERROR condition 
action by default handler, 17-13 
default ON-unit action, 17-9 
errors, B-29 
for file errors, 5-9 
signal value, 17-3 
signaled by default ON-unit, 17-13 
Error (severity) 
meaning to compiler, 2-10 
numeric value and meaning, 16-2 
Errors 
at run time, 4 2 
compiler, B-1 to B-27 
message format, 2-10 
display system messages, 4-5 
ENVIRONMENT options, 6-3 
handling, 17-1 
file errors, 5-9, 5-11 
indexed sequential files, 12-12 
linking, 3-3 
relative files, 11-7 
Event flag 
as argument, 19-3 
clear, 19-16 to 19-17 
wait for, 19-16 to 19-17, 19-20 
with a timer, 19-16 to 19-17 
EXE file type, 3-5 
Executable image, create, 3-1 
Execute 
command procedures, 4-7 
programs, 4-1 
EXIT command, 4-2, 4-5 
Expiration date of file 
determine, 8-3 
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Files (Cont.), 
carriage control, 9-7 
compiler input and output, 2-7 
creating, 10-1 
creation date, 6-16 
example, 19-14 
deleting, 6-19 
error conditions, 5-9 
expiration date, 6-19 
example, 19-14 
indexed sequential, 6-27, 9-2, 12-1 to 12-13 
linker input and output, 3-4 
locked, 13-6 
magnetic tapes, 10-2 
mailboxes, 20-3 
network access, 21-1 
opening, ENVIRONMENT options, 6-3 
ownership, 13-1 
specify, 13-2 
position at beginning, 8-9 
printer format, 9-7 
process permanent, 5-5 
protection, 13-1 
specify, 13-3 
reading and writing, 7-4, 7-11, 10-3, 
11-5 to 11-6, 12-9 to 12-10 
relative, 9-2, 11-1 to 11-7 
sequential, 9-2, 10-1 to 10-5 
sharing, 13-4 to 13-8 
sorting, 22-1 to 22-3 
example, 22-2 to 22-3 
specify size, 6-22 
stream, 9-7 
temporary, 6-45 
truncate at end-of-file, 6-46 
see also Indexed sequential files, 
Relative files, Sequential files 
FINISH condition, 4-2 
at image exit, 4-5 
effect of MAIN option, 4-3 
errors, B-29 
signaled by default handler, 17-13 
signaled by STOP statement, 17-12 
STOP statement in ON-unit, 17-15 
Fixed control area, 9-6 
determine size, 6-24, 8-3 
in printer format file, 6-35 
read, 7-5 
specify size, 6-23 
writing or rewriting, 7-3 
example, 7-4 
FIXED_CONTROL__FROM option, 
7-2 to 7-3, 9-6 


FIXED_CONTROL_SIZE 
(ENVIRONMENT option), 6-6, 
6-23, 9-6, C-2 

FIXED__CONTROL_SIZE__TO 
(ENVIRONMENT option), 6-6, 
6-24, C-2 

FIXED_CONTROL_TO option, 7-2, 
7-5, 9-6 

FIXED_LENGTH_RECORDS 
(ENVIRONMENT option), 6-6, 
6-24, 9-5, C-2 

determine if set, 8-3 
Fixed-length records, 6-24, 9-5 
specify record size, 6-28 
FIXEDOVERFLOW condition 
errors, B-29 
sample ON-unit, 17-4 
signal value, 17-3 
Floating-point, select default format, 2-5 
FLUSH built-in subroutine, 8-8 
Foreign command, define, 4-10 
Form feeds, specify in printer format, 
6-36 to 6-37 
Formats, of records, 9-5 
FORTRAN programs 
COMMON block, 18-3 
passing arrays, 14-6 

FP (Frame Pointer), 14-1 
when condition signaled, 17-5 

Free storage in area, 18-5, 18-7, 
(18-12 to 18-13 

FTN carriage control, 8-5 

/FULL qualifier, 3-6 

Function codes (I/Q), 19-18 

for mailbox I/O, 20-6 


G 


/G_FLOAT qualifier, 2-5 
G floating-point format, 2-5 
General register 0, 4-5, 16-1 
General registers, saved, 14-2 
GET statement 
default file title, 5-6 
interpretation of end-of-line, 
6-26 
NO_ECHO option, 7-8 
suppress display of input, 7-8 
valid options, 7-2 
with NO__FILTER option, 7-8 
with PROMPT option, 7-9 
GETBINTIM procedure, 19-15 
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Initialize 
area, 18-5, 18-10 to 18-11 
global symbols, 15-3 
INITIALIZE command, 1-9, 10-2 
INPUT attribute 
determine if file has, 8-5 
effect on file sharing, 13-4 
Input files 
compiler, 2-7 
define for program I/O, 5-2 
Input/output 
block, 9-4 
file specifications, 5-2 
optimization, 5-11 
overview of VAX/VMS features, 5-1 
PL/I and RMS, 5-1 
using mailboxes, 20-1, 20-4 to 20-8 
see also Files, I/O entries 
Integer overflow, detect, 17-4 
Integer values, assign to bit strings, 
6-36, 16-5 
Internal variables, program sections, 
18-3 
Interrupting 
DCL commands, 1-3 
program execution, 4-4 
the PL/I compiler, 2-11 
Invoking 
non-PL/I procedures, 14-1 
PL/I compiler, 2-2 
the linker, 3-2 
Item list (SYS$GETJPI), 19-24 
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$J BCMSGDEF, 19-5 
$JPIDEF, 19-5, 19-24 


K 


KEY condition, 5-9 
attempting to change a key, 12-9 
duplicate keys, 12-9 
errors, B-29 
sample ON-unit, 11-7, 12-13 
signal value, 17-3 
Key fields 
define, 12-5 
use compiler storage map, 12-5 
Key number, see Index number 


KEY option 
required with INDEX_-NUMBER, 7-5 
specify for indexed file, 12-8 
specify for relative file, 11-5 
Key values 
in block I/O, 6-12 
in relative files, 11-1 
indexed sequential files, 12-1 
valid data types, 12-7 
KEYED attribute, 9-2 
create relative file, 11-2 
determine if file has, 8-5 
Keys 
alternate, 12-1 
access file using, 7-1, 7-7 
access records by, 12-11 
define, 12-6 
specify numbers, 12-8 
binary, 12-8 
character-string, 12-8 
decimal, 12-8 
define for SORT, 22-2, 22-6 
determine number, 8-5 
duplicate, 12-9 
for relative files, 11-1 
generic matching, 12-12 
handle duplicate errors, 12-13 
handle invalid data type errors, 12-13 
handle key not found errors, 
11-7, 12-13 
match key values 
match greater, 7-6, 12-12 
match greater or equal, 7-7 
modify alternate, 12-9 
options, 12-9 
specify alternate, 12-11 
specify index number, 6-26 
specify position in record, 12-5 
specifying, 12-5 
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Labels, magnetic tape, 10-2 
Length 
of fixed control area, 9-6 
of variable-length records, 9-6 
Level-one procedure, 2-9, 3-1 
identify in listing, A-3 
LIB$ESTABLISH, 17-1 
LIB$GET__FOREIGN, 4-10 
example, 4-11 to 4-12 
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Machine code listing, A-7 to A-9 
/MACHINE__CODE qualifier, 2-5, A-7 
Magnetic tapes, 10-2 
allocate drive, 5-3 
block I/O, 6-12 
blocking, 10-3 
labels, 10-2 
mount next volume, 8-8 
multivolume, 8-8, 10-4 
positioning, 6-17, 10-3 
rewind, 8-9 
rewind on close, 6-40 
rewind on open, 6-40 
set expiration date, 6-19 
example, 19-14 
specify block size, 6-12 
version numbers, 10-2 
volume switching, 10-4 
Mailbox messages 
type codes, 20-4 
Mailboxes, 20-1 to 20-8 
assign channel example, 19-12 
create, 19-10 to 19-11 
delete, 19-12 to 19-13, 20-1, 20-3 
determine if file is a mailbox, 8-6 
specify OPEN, 20-3 
temporary and permanent, 20-1 
MAIN option 
as program transfer address, 3-3 
default condition handling, 17-12 
effect on program termination, 4-2 
in concatenated input files, 2-9 
Main procedure 
default condition handling, 17-12 
exit handler, 4-1 
FINISH ON-unit, 4-3 
pass data, 4-9 to 4-15 
return status values, 4-5 
Map file (linker), 3-6 
contents of brief, 3-6 
contents of default, 3-6 
contents of full, 3-6 
specify name for, 3-6 
MAP file type, 3-5 
/MAP qualifier, 3-6 
Mapping windows, 6-39 
MATCH_—GREATER option, 7-2, 7-6 
MATCH.-GREATER_EQUAL option, 7-2, 
7-7 
example, 12-12 


Maximum reeord number, 11-2 
determine, 8-4 
handling error condition, 11-7 
specify, 6-27 
MAXIMUM__RECORD__NUMBER 
(ENVIRONMENT option), 6-7, 6-27, 
11-2, -C-2 
Maximum record size 
determine, 8-4 
specify, 6-28 
MAXIMUM__RECORD-__SIZE 
(ENVIRONMENT option), 6-7, 6-28, 
9-5 to 9-6, 11-3, C-2 
Mechanism array arguments, 17-6 
display, 17-6 
Member number, of file’s owner, 6-33 
determine, 8-4 
Memory, 18-1 
Memory allocation listing, see Map file 
(linker) 
Message identification, B-1, B-30 
suppress display in messages, 2-11 
Message number, 16-2 
code in global symbol name, 16-4 
set, 16-5 
Messages, B-1 to B-39 
after image exit, 4-5 
compiler, B-1 to B-27 
format, 2-10 
severity, B-1 
correspondence to status values, 16-2 
displayed at run time, 4-2 
facility name, 2-10 
identification, 2-10 
linker, 3-3 
run-time, B-28 to B-39 
format, 4-3 
severity, 2-10 
suppress compiler warnings, 2-11 
Module name 
assigned by compiler, 2-1 
in concatenated input files, 2-9 
in run-time traceback, 4-3 
object module, 3-9 
table, 3-7, 3-9 
text module, 2-13 
specify name, 2-14, 2-16 
MOUNT command, 1-9, 5-3, 10-2 
Multiblock count 
determine, 8-4 
specify, 6-29 ; 
MULTIBLOCK__COUNT (ENVIRONMENT 
option), 5-12, 6-7, 6-29, C-2 
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OPTIONS option 
ENTRY attribute, 14-12 
I/O statements, 7-1 
/OPTIONS qualifier (LINK command), 3-4 
OPTIONS (VARIABLE), 14-12 to 14-14 
OUTPUT attribute 
create a new file, 10-1 
determine if file has, 8-5 
effect on file sharing, 13-4 
Output files (program) 
define, 5-2 
spool to line printer, 6-48, 10-5 
OVERFLOW condition 
signal value, 17-3 
Owner of a file 
define, 13-2 
determine, 8-4 
OWNER_—GROUP (ENVIRONMENT option), 
6-7, 6-32, 13-2, C-2 
OWNER_—MEMBER (ENVIRONMENT 
option), 6-8, 6-33, 13-2, C-2 
OWNER—PROTECTION (ENVIRONMENT 
option), 6-8, 6-34, 13-3, C-2 
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Page number of print files 
determine current, 8-5 
Page size of print files 
determine current, 8-5 
Parameter descriptors 
non-PL/I procedures, 14-3 
omitting, 14-14 
VALUE attribute, 14-4 
Parentheses, enclose arguments, 14-6, 14-10 
PC (Program Counter), 14-2 
display in ON-unit, 17-6 
in run-time traceback, 4-4 
when condition signaled, 17-5 
PL/I compiler 
diagnostic messages, B-1 to B-27 
functions, 2-1 
invoking, 2-2 
listing file, 2-5 
listing options, 2-4 
options, 2-3 
PL/I condition values, 17-3 
PLI command, 1-1 to 1-2, 2-1 to 2-9, 3-8 
diagnostic messages, B-1 to B-27 
format, 2-10 
examples, 2-7 to 2-8 
qualifiers, 2-3 
specify libraries, 2-15 


PLI file type, 2-3, 2-13 
PLI_FILE__DISPLAY structure, 8-2 
device attributes, 8-6 
ENVIRONMENT information, 8-3 
file attribute information, 8-5 
PLI$LIBRARY, define in more than one 
logical name table, 2-17 
PLISYSDEF.TLB, 2-17, 19-5 
$CHFDEF, 17-5 
$STSDEF, 16-3 
SORT procedure declarations, 22-1 
symbolic definition modules, 19-5 
system service declarations, 19-1 
Pointers, pass as actual arguments, 14-7 
Position 
files 
using READ, 9-3 
using REWIND, 8-9 
key (in indexed file), 12-5 to 12-6 . 
magnetic tapes, 6-17, 6-40, 10-3 
$PQLDEF, 19-5 
Primary key, 12-1, 12-8 
PRINT attribute, 9-7 
determine if file has, 8-5 
PRINT command, 1-5 
Printer device, see Line printer 
Printer format, 6-35, 9-7 
detect, 8-4 
size of fixed control area, 6-35 
specify line and form feeds, 6-36 to 6-37 
PRINTER_FORMAT (ENVIRONMENT 
option), 6-8, 6-34, 9-7, C-2 
characters, 6-35 
example, 6-36 
Procedures 
block activations, 14-1 
libraries, 3-7 
non-PL/I, 14-1 
pass as arguments, 14-4 
run-time, 3-1 
Process, obtain information, 19-24 
Process logical name table, 1-6, 5-5 
Process permanent files, 5-5 
Program Counter, see PC (Program Counter) 
Program output 
redefine SYSPRINT, 5-3 
spool to line printer, 5-2, 6-43, 10-5 
submit to batch queue, 6-10 
Program sections 
attributes, 18-1 to 18-2 
COMMON blocks, 18-3 
created by compiler, 2-1, 18-2 
for external variables, 18-2 
for file constants, 18-3 
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References 
global symbols 
resolve, 15-5 
to system services, 19-1 
unresolved, 3-4 
Registers 
saved, 14-2 
variables in, 2-6 
Relative files, 9-2, 11-1 to 11-7 
creating, 11-2 
using SORT, 22-2 
error handling, 11-7 
examples, 11-1, 11-4 
populate, 11-5 . 
rewind to first occupied cell, 8-9 
specify maximum record number, 6-27 
updating, 11-6 
Relative record number, 11-1 
maximum, 11-2 
Remote file access, 21-1 
RENAME command, 1-9 
RESIGNAL built-in subroutine, 17-9 to 17-10 
Resolution of references, 3-1 
global symbols, 15-5 
Retrieval pointers 
determine number, 8-4 
RETRIEVAL_POINTERS (ENVIRONMENT 
option), 5-12, 6-8, 6-39, C-2 
RETURN statement, 16-1 
effect of status values, 4-5 
effect on call stack, 14-2 
main procedure, 4-1 
specify value, 4-5 
return status value, 16-1 
Return status values, 16-1 
format, 16-1 
I/O requests, 19-20 
set fields, 16-5 
system services, 19-6 
test for success or failure, 16-3 
testing, 16-3 
RETURNS attribute, main procedure, 4-5 
REWIND built-in subroutine, 8-9 
effect on locked records, 13-7 
REWINDON__CLOSE (ENVIRONMENT 
option), 6-8, 6-40, 10-3, C-2 
determine if set, 8-4 
REWIND__ON__OPEN (ENVIRONMENT 
option), 6-8, 6-40, C-2 
determine if set, 8-4 
REWRITE statement, valid options, 7-2 
RFA (Record File Address), see Record 
Identification 


RMS 
condition values, 12-13, 17-3 
multibuffering, 6-31 
relationship to PL/I, 5-1 
Routine name 
in run-time traceback, 4-4 
RUN command, 1-2, 4-1 
Run-time errors, 4-2 
messages, B-28 to B-39 
Run-time library, 3-11 
Run-time procedures 
linking, 3-1 
Running programs, 4-1 
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SCALARVARYING (ENVIRONMENT 
option), 6-9, 6-41, C-2 
determine if set, 8-4 
Search order 
INCLUDE file libraries, 2-16 
logical name tables, 1-7 
object module libraries, 3-9 
logical name tables, 3-10 | 
ON-units, 17-12 to 17-14 
$SECDEF, 19-5 
Sections, program, see Program sections 
Segmented character-string keys, 12-8 
Sequence numbers, in fixed control area, 7-4 
Sequential access to files, 9-3 
SEQUENTIAL attribute, 9-2 
determine if file has, 8-5 
Sequential files, 9-2, 10-1 to 10-5 
append records to, 10-1 
create, 10-1 
magnetic tapes, 10-2 to 10-4 
Services, system, see System services 
SET DEFAULT command, 1-6, 1-9 
SET MESSAGE command, 2-11 
SET PROTECTION command, 13-3 
Severity, 16-2 
of compiler errors, 2-10 
of conditions, 17-3 
of resignaled condition, 17-13 
suppress display in messages, 2-11 
Shareable image file, linker options file for, 
3-5 . 
Shareable image library, VMSRTL.EXE, 
3-11 
SHARED__READ (ENVIRONMENT option), 
6-9, 6-42, 13-4, C-2 
determine if set, 8-4 
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SYS$ASSIGN system service, 19-12, 19-18 
SYS$BINTIM system service, 19-14 
SYS$CLREF system service, 19-16 to 19-17 
SYS$COMMAND, 5-6 
SYS$CREMBX system service, 19-10 
SYS$DELMBxX system service, 19-12, 20-3 
SYS$DISK, 5-6 
SYS$ERROR, 5-6 
SYS$EXIT system service, 4-2 

called by STOP statement, 17-12 
SYS$FORCEX system service, 4-2 
SYS$GETJPI system service, 19-24 to 19-27 
SYS$INPUT, 5-6 
SYS$LIBRARY, 2-17, 3-11 

redefine, 2-17 
SYS$NET, 21-5 
SYS$OUTPUT, 5-6 

output compiler listing to, 2-8 
SYS$PRINT, 6-43 
SYS$QIO system service, 19-18 

mailboxes, 20-6 
SYS$SETIMR system service, 19-16 to 19-17 
SYS$TRNLOG system service, 

4-13 to 4-15, 19-8 to 19-9 
SYS$WAITFR system service, 19-16 to 19-17 
SYSIN, 5-6 

redefine, 5-3 . 
SYSNAM user privilege, 1-7 
SYSPRINT, 5-6 
redefine, 5-3 
System libraries 
object module, 3-11 
PLISYSDEF.TLB, 2-17 
System logical name table, 1-7, 5-5 
System messages, 4-5 
System services, 19-1 to 19-27 
arguments, 19-3 
symbolic definition files, 19-4 
test return status, 19-6 
variable-length argument lists, 19-4 
SYSTEM_-PROTECTION (ENVIRONMENT 
option), 6-9, 6-44, 13-3, C-2 
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Tables 
global symbol, 3-7 
logical name, 1-6 to 1-7, 5-5 
Tapes, see Magnetic tapes 
Task-to-task communication, 21-2 to 21-5 
TEMPORARY (ENVIRONMENT option), 
6-9, 6-45, C-3 
determine if set, 8-4 
use with FILE_ID option, 6-21 


Temporary defaults for 
file specifications, 1-5 
Temporary files, 6-45 
Terminal 
I/O with $QIO, 19-20 
TT logical name, 19-20 » 
Terminal input 
display prompting message, 7-9 
suppress display, 7-8 
Termination (program), 4-1 
Text libraries, 2-7, 2-13 
Text modules, specify name for, 2-14, 2-16 
Time 
convert ASCII string to binary, 19-14 
specify for ENVIRONMENT options, 19-14 
system 64-bit value, 19-14 to 19-15 
Timer, set with system service, 19-16 to 19-17 
TIMRB, 19-24 to 19-27 
TIMRE, 19-24 to 19-27 
TITLE option, 5-2 
default for SYSIN, 5-6 
default for SYSPRINT, 5-6 
determine expanded value, 8-5 
specify logical name, 5-4 
specify mailbox, 20-3 
specify remote file, 21-2 
TLB file type, 2-3, 2-7 
Traceback 
compiler information, 2-2 
exclude from image, 4-4 
following condition signal, 17-13 to 17-14 
for run-time errors, 4-3 
file errors, 5-11 
information, 4-4 
linker information, 3-7 
specify at compile time, 2-4 
specify at link time, 3-7 
/TRACEBACK qualifier, 3-7 
Translate logical names, 1-7, 
4-18, 5-5, 19-8 to 19-9 
TRUNCATE (ENVIRONMENT option), 
6-9, 6-46, C-3 
determine if set, 8-4 
TT logical name, assign channel, 19-20 
Type-ahead buffer, purging, 7-10 
TYPE command, 1-5 
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UIC, see User identification code 
UNDEFINEDFILE condition, 5-9 
ENVIRONMENT option conflicts, 6-3 
errors, B-29 
invalid file specifications, 5-3 
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